MCP 服务器

MCP Server

Provides remote filesystem operations, git repository management, and process execution capabilities for AI agents through the Model Context Protocol.

README

MCP Server

A high-performance Model Context Protocol (MCP) server providing remote filesystem, git, and process operations. Built with Mastra and Bun for fast execution and distributed as compiled binaries for easy deployment.

Features

Filesystem Operations

fs.exists - Check if file/directory exists
fs.mkdir - Create directories (with recursive option)
fs.readdir - Read directory contents (with file type information)
fs.readFile - Read files (text and binary data)
fs.stat - Get detailed file/directory statistics
fs.writeFile - Write files (text and binary data)
fs.fileSize - Get file size
fs.delete - Delete files/directories (with recursive option)

Git Operations

git.status - Get repository status (staged, modified, untracked files)
git.log - Get commit history with optional filtering
git.diff - Show differences between commits, branches, or working tree
git.branch - List branches and show current branch
git.remote - List configured remote repositories
git.tag - List all repository tags
git.init - Initialize a new git repository
git.clone - Clone remote repository (with optional depth and branch)
git.add - Add files to staging area
git.commit - Create commit with staged changes
git.push - Push local commits to remote
git.pull - Pull and merge changes from remote
git.checkout - Switch or create branches
git.merge - Merge changes from another branch
git.createTag - Create new tag at current commit

Process Operations

process.spawn - Spawn a process with arguments and capture output
process.exec - Execute shell commands

Key Capabilities

Binary data support via base64 encoding
Full TypeScript support with Zod schema validation
Built on MCP (Model Context Protocol) for AI agent integration
Server-Sent Events (SSE) for real-time communication
Cross-platform binary distribution (Linux x64/ARM64, macOS x64/ARM64)
NPM package for client library integration
Bun runtime for high performance

Installation

Option 1: Install Binary (Recommended)

Download and execute the install script:

curl -fsSL https://raw.githubusercontent.com/supervise-dev/mcp/master/install.sh | bash

Specify a custom install directory:

INSTALL_DIR=/usr/local/bin curl -fsSL https://raw.githubusercontent.com/supervise-dev/mcp/master/install.sh | bash

Install a specific version:

curl -fsSL https://raw.githubusercontent.com/supervise-dev/mcp/master/install.sh | bash -s v1.0.0

Common install directories:

/usr/local/bin - System-wide binary (requires sudo for some systems)
$HOME/.local/bin - User-specific binary (add to PATH if needed)
. - Current directory (default)

Security tip: Review the script before executing:

curl -fsSL https://raw.githubusercontent.com/supervise-dev/mcp/master/install.sh -o install.sh
cat install.sh  # Review the script
bash install.sh

Option 2: Install as NPM Package

npm install @supervise-dev/mcp
# or
bun install @supervise-dev/mcp

Option 3: Development Installation

For local development:

bun install
bun run build

Quick Start

Running the Server

Start the MCP server (default port: 1234):

# Using the binary
./dist/mcp

# Or with a custom port
SV_MCP_PORT=4000 ./dist/mcp

# Development mode with hot reload
bun run dev

The server will be available at:

SSE endpoint: http://localhost:1234/sse
Message endpoint: http://localhost:1234/message

Client Usage

import { MCPClient } from "@mastra/mcp";

const client = new MCPClient({
  url: "http://localhost:1234",
  ssePath: "/sse",
  messagePath: "/message",
});
await client.connect();

// Filesystem operations
await client.callTool("fs.writeFile", { path: "/file.txt", data: "Hello" });
const { data } = await client.callTool("fs.readFile", { path: "/file.txt" });
await client.callTool("fs.mkdir", { path: "/dir", recursive: true });
const { files } = await client.callTool("fs.readdir", { path: "/dir" });

// Git operations
await client.callTool("git.clone", { url: "https://github.com/user/repo.git", path: "/repo" });
const status = await client.callTool("git.status", { repoPath: "/repo" });
await client.callTool("git.add", { repoPath: "/repo", files: ["."] });
await client.callTool("git.commit", { repoPath: "/repo", message: "Update" });
await client.callTool("git.push", { repoPath: "/repo", remote: "origin", branch: "main" });

// Process operations
const output = await client.callTool("process.spawn", { command: ["ls", "-la"] });
console.log(output.stdout, output.exitCode);

API Reference

All tools are invoked via client.callTool(toolId, input). See the Features section above for complete tool listings.

Common Input Patterns:

Filesystem: { path: string, ...options }
Git: { repoPath: string, ...options }
Process: { command: string[], cwd?: string, env?: Record<string, string> }

Process Output:

interface ProcessOutput {
  stdout: string;
  stderr: string;
  exitCode: number;
  success: boolean;
}

Build & Development

Scripts

# Development
bun run dev                  # Run server with hot reload

# Build
bun run build               # Build default binary for current platform
bun run build:darwin-arm64  # Build macOS ARM64
bun run build:darwin-x64    # Build macOS x64
bun run build:linux-arm64   # Build Linux ARM64
bun run build:linux-x64     # Build Linux x64

# Code Quality
bun run format              # Format with Prettier
bun run lint                # Run ESLint
bun run typecheck           # Run TypeScript check

Architecture

Built with modular design: Server (src/index.ts) handles HTTP/SSE, with separate modules for filesystem (src/tools/fs/), git (src/tools/git/), and process (src/tools/process/) operations. Each module includes query/mutation handlers and Zod type definitions.

MCP Protocol

Implements the Model Context Protocol for AI agent integration, using Server-Sent Events (SSE) for real-time bidirectional communication with full type safety and schema validation.