Local MCP Bridge Typescript

MCP SSE桥

一个本地网桥服务器，允许浏览器扩展和MCP客户端（Claude.ai、HuggingFace Chat、Cursor等）连接到基于stdio的MCP服务器（如 php artisan boost:mcp)使用SSE或流式HTTP传输。

与官方合作建造 @模型上下文协议/sdk 用于生产就绪、类型安全的MCP协议处理。

______________________________________________________________________

模式

桥接模式

在浏览器客户端和生成的stdio MCP进程之间转发JSON-RPC消息。

Browser / Extension → Bridge (localhost:3000) → stdio → php artisan boost:mcp

代理模式

内置MCP服务器，带有文件系统和命令执行工具，无需外部进程。

Browser / Extension → Bridge (localhost:3000) → built-in McpServer → File System / Commands

______________________________________________________________________

安装

npm install
# or
pnpm install

构建与运行

# Build
npm run build

# Start
npm start

# Dev (build + run)
npm run dev

# Watch mode
npm run watch

开发脚本

npm run types          # Type checking
npm run lint           # Lint
npm run lint:fix       # Lint and auto-fix
npm run format         # Format with Prettier
npm run format:check   # Check formatting
npm run check          # types + lint + format check
npm test               # Run tests

______________________________________________________________________

配置

所有配置都是通过环境变量进行的。复制 .env.example 到 .env 并调整：

cp .env.example .env

关键变量：

工作空间配置

创建 .mcp-agent/config.json 在项目根目录中覆盖每个项目的默认值：

{
  "version": "1.0.0",
  "permissions": {
    "allowedPaths": ["./"],
    "allowedCommands": ["npm", "git", "ls", "grep"],
    "enableCommandExecution": true
  },
  "limits": {
    "maxFileSize": 5242880,
    "commandTimeout": 30000
  }
}

全局用户配置

创建 ~/.mcp-agent.json 要在所有工作区中设置默认值，请执行以下操作：

{
  "version": "1.0.0",
  "permissions": {
    "allowedPaths": ["~/Projects", "~/Documents"],
    "deniedPaths": ["/etc", "/sys", "~/.ssh"],
    "allowedCommands": ["ls", "grep", "find", "cat", "git", "npm"],
    "enableCommandExecution": true
  },
  "limits": {
    "maxFileSize": 10485760,
    "commandTimeout": 30000
  }
}

优先：工作区配置>全局配置>默认值

______________________________________________________________________

端点

传统SSE传输（MCP规范2024-11-05）

GET /sse --桥接模式

生成stdio MCP进程并打开SSE流。

http://localhost:3000/sse?command=php&args=["artisan","boost:mcp"]&cwd=/path/to/laravel

POST /sse --桥接模式

向活动网桥会话发送JSON-RPC消息。

GET /agent --代理模式

使用给定工作区的内置工具启动代理会话。

http://localhost:3000/agent?workspace=/path/to/project

POST /agent --代理模式

向活动代理会话发送JSON-RPC消息。

______________________________________________________________________

可流式HTTP传输（MCP规范2025-03-26）

GET|POST /mcp --桥接模式

http://localhost:3000/mcp?command=php&args=["artisan","boost:mcp"]&cwd=/path/to/laravel

GET|POST /mcp/agent --代理模式

http://localhost:3000/mcp/agent?workspace=/path/to/project

______________________________________________________________________

监控

curl http://localhost:3000/health
curl http://localhost:3000/metrics

______________________________________________________________________

代理模式工具

文件系统

Git

代码质量

执行

网络

______________________________________________________________________

安全

• 路径遍历预防 --在访问之前，所有路径都解析为绝对路径
• 命令注入预防 — spawn() 使用args数组，从不进行shell插值
• 命令白名单 --只有 ALLOWED_COMMANDS 可以在桥接模式下生成
• 拒绝路径 --系统目录(/etc, /sys, ~/.ssh等）默认情况下被阻止
• 文件大小限制 --阻止读取大文件（默认为10 MB）
• 命令超时 --终止长时间运行的命令（默认30秒）

______________________________________________________________________

故障排除

服务器无响应

curl http://localhost:3000/health/live

连接被拒绝/CORS错误

确保 CORS_ORIGIN=* 在你的 .env （或客户的具体来源）。

不允许命令

将命令添加到 ALLOWED_COMMANDS 在 .env 并重新启动：

ALLOWED_COMMANDS=php,python,python3,node,npx,uvx,deno,your-command

拒绝访问路径

检查 .mcp-agent/config.json 在您的工作区中--确保路径在 allowedPaths 而不是在 deniedPaths.

日志

结构化日志被写入 .mcp-agent/logs/:

.mcp-agent/logs/combined.log   # All logs
.mcp-agent/logs/error.log      # Errors only

______________________________________________________________________

项目结构

src/
├── index.ts              # Entry point — Express app, routes, graceful shutdown
├── config/               # Environment validation and config file loader
├── server/               # McpServer setup and tool registration (Agent Mode)
├── tools/                # Individual tool implementations
│   ├── filesystem.ts     # File read/write/edit/delete
│   ├── git.ts            # Git operations
│   ├── commands.ts       # Shell command execution
│   ├── formatting.ts     # Code formatting and linting
│   └── web.ts            # Web search and fetch
├── transport/            # Streamable HTTP bridge and agent handlers
├── middleware/           # Request ID, validation, metrics middleware
├── metrics/              # Prometheus metrics
├── health/               # Health check logic
├── security/             # Path and command validators
├── utils/                # Logger, shutdown, errors, retry, workspace init
└── types/                # All shared TypeScript types

______________________________________________________________________

许可证

麻省理工学院