AI导哈

模型上下文协议服务

一个基于TypeScript的模型上下文协议(MCP)服务器，通过stdio提供JSON-RPC 2.0接口，为AI助手如Claude暴露Git仓库工具和项目资源浏览功能。

  • by devaloi
  • TypeScript
  • 本地部署
  • 1 星标
  • 更新于
在 GitHub 查看 devaloi/mcpserve-ts

使用说明

mcpserve ts

A. 模型上下文协议 TypeScript中的（MCP）服务器——通过stdio手动滚动JSON-RPC 2.0。为Claude等AI助手公开Git存储库工具和项目资源浏览。

三重投资组合的一部分： 走 · python · TypeScript

特性

  • 手动滚动MCP协议 --基于stdio的JSON-RPC 2.0，不依赖SDK
  • 8工具 --Git操作、项目浏览、安全shell执行
  • 3种资源类型 --文件内容、package.json、目录树
  • 路径沙盒 --所有文件操作仅限于项目根目录
  • Zod验证 --对每个工具调用进行严格的输入验证
  • TypeScript严格 --零 any 类型，全类型安全
  • 最小依赖性 --只有 zod 在运行时

快速开始

# Install
git clone https://github.com/devaloi/mcpserve-ts.git
cd mcpserve-ts
npm install
npm run build

# Run
PROJECT_ROOT=/path/to/your/project node dist/index.js

# Test
npm test

Claude桌面配置

添加 ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "mcpserve-ts": {
      "command": "node",
      "args": ["/path/to/mcpserve-ts/dist/index.js"],
      "env": {
        "PROJECT_ROOT": "/path/to/your/project"
      }
    }
  }
}

工具

工具 说明 参数
git_status 显示工作树状态 path?
git_diff 显示阶段性或非阶段性更改 path?, staged?
git_log 显示提交历史记录 path?, limit?
git_blame 逐行显示作者身份 file
project_tree 列出目录结构 path?, depth?
read_file 读取文件内容 path
search_files 使用正则表达式搜索 pattern, path?, glob?
run_command 执行分配的命令 command, args?

壳牌许可清单

仅允许通过以下方式执行这些命令 run_command: ls, cat, wc, head, tail, find, grep

资源

URI 描述 MIME类型
file:///{path} 项目文件内容 自动检测到
project:///package.json 解析包.json 应用程序/json
project:///tree 目录树 文本/纯文本

建筑

src/
├── index.ts              # Entry point: register tools, start stdio
├── server.ts             # MCP server: method dispatch
├── protocol.ts           # JSON-RPC 2.0 types and codec
├── transport.ts          # Stdio transport (line-delimited JSON)
├── config.ts             # Zod-validated env config
├── tools/
│   ├── registry.ts       # Tool registry (name → handler + schema)
│   ├── git.ts            # Git tools: status, diff, log, blame
│   ├── project.ts        # Project tools: tree, read, search
│   └── shell.ts          # Safe shell: allowlisted commands only
├── resources/
│   ├── provider.ts       # Resource provider interface
│   ├── project.ts        # File resources (file:///path)
│   └── package.ts        # package.json + tree resources
├── lib/
│   ├── constants.ts      # Shared constants (limits, skip dirs)
│   ├── git.ts            # Git CLI wrapper (execFile)
│   ├── sandbox.ts        # Path sandboxing
│   ├── schemas.ts        # Zod schemas for tool inputs
│   └── tree.ts           # Shared directory tree builder

MCP协议

实施 模型上下文协议 规范：

  • 运输： 基于stdio的JSON-RPC 2.0（换行符分隔的JSON）
  • 协议版本： 2024-11-05
  • 方法： initialize, ping, tools/list, tools/call, resources/list, resources/read
  • 通知： notifications/initialized

握手示例

# Initialize
echo '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"test","version":"0.1.0"}}}' | node dist/index.js

配置

变量 默认值 描述
PROJECT_ROOT cwd 文件操作的根目录
LOG_LEVEL info 日志级别：调试、信息、警告、错误

日志被写入stderr；stdout保留用于JSON-RPC消息。

发展

npm run build       # Compile TypeScript
npm run dev         # Watch mode
npm run test        # Run tests (Vitest)
npm run typecheck   # Type-check without emitting
npm run lint        # ESLint
make all            # lint + typecheck + build + test

技术栈

组件 选择
运行时 Node.js 20+
语言 TypeScript 5（严格）
协议 手动JSON-RPC 2.0
验证 Zod
测试 Vitest
Linting ESLint+打字ESLint

许可证

麻省理工学院

贡献

看 贡献.md.PR欢迎运行 npm test && npm run lint 在提交之前。

相关 MCP