MCP 工具中心

一个模块化、可扩展的 Model Context Protocol (模型上下文协议) 多服务器中心 —— 专为 IT 自动化团队使用 TypeScript 构建。

让你的 LLM 能够访问现实世界的工具：文件、Git、网页内容和持久化内存。通过 Ansible 同时部署到任意数量的客户端机器上。

架构

mcp-tool-hub/
├── packages/
│   ├── core/              ← Shared types + BaseMCPServer abstract class
│   ├── server-filesystem/ ← Sandboxed local file access (read/write/list/delete)
│   ├── server-git/        ← Git log, diff, file contents, branches, status
│   ├── server-fetch/      ← Web fetching: HTML, JSON APIs, URL health checks
│   └── server-memory/     ← Persistent JSON knowledge base (survives restarts)
├── host/                  ← Orchestrator: registry + CLI + stdio JSON interface
├── ansible/               ← Playbook, inventory, systemd service templates
└── docs/                  ← How to add new servers (with template)

该架构遵循 Model Context Protocol 模式：

每个服务器都是完全独立的 —— 拥有自己的包和构建方式
主机中的 registry (注册表) 在运行时将 toolName 映射到 server
CLI 暴露了一个 stdio JSON 接口 —— 任何 LLM 集成都会在 stdin 上发送 {"toolName":"...", "arguments":{...}}，并从 stdout 读取结果
添加新服务器 = 创建一个包，扩展 BaseMCPServer，并在 cli.ts 中注册

快速入门

1. 安装与构建

git clone https://github.com/your-org/mcp-tool-hub.git
cd mcp-tool-hub
npm install
npm run build

2. 配置

cp .env.example .env
# Edit .env with your paths and settings

3. 运行

# Via npm
npm run start --workspace=host

# Or directly
node host/dist/cli.js

4. 调用工具

向 stdin 发送 JSON，从 stdout 获取 JSON：

echo '{"toolName":"read_file","arguments":{"path":"hello.txt"}}' | node host/dist/cli.js

可用工具

📁 文件系统服务器

所有操作均在 MCP_FS_ROOT 中进行沙盒化。路径遍历 (../) 被拦截。

工具	描述
`read_file`	读取文件内容 (utf8 或 base64)
`write_file`	写入或追加到文件
`list_directory`	列出目录内容 (可选递归)
`delete_file`	删除文件
`move_file`	移动或重命名文件
`get_file_info`	获取路径的大小、日期和类型

🔀 Git 服务器

只读。无写入操作。

工具	描述
`git_log`	仓库或文件的提交历史
`git_show_file`	特定提交/分支下的文件内容
`git_diff`	两个引用之间的差异
`git_status`	工作树状态
`git_branches`	列出分支 (本地 + 可选远程)
`git_show_commit`	完整的提交详情和差异

🌐 抓取服务器

支持通过 MCP_FETCH_ALLOWED_DOMAINS 设置可选的域名白名单。

工具	描述
`fetch_url`	从 URL 抓取 HTML 或文本
`fetch_json`	抓取并解析 JSON API 响应
`check_url`	检查 URL 是否可达 (HEAD 请求)

🧠 内存服务器

重启后持久保存。由 JSON 文件支持。

工具	描述
`memory_set`	使用键、命名空间和标签存储值
`memory_get`	按键检索值
`memory_search`	对所有条目进行全文搜索
`memory_delete`	删除条目
`memory_list_namespaces`	列出所有命名空间及其计数
`memory_clear_namespace`	删除命名空间中的所有条目

Ansible 部署

同时部署到你所有的客户端机器：

cd ansible

# First time
ansible-playbook -i inventory.yml deploy-mcp-hub.yml

# Update only (rebuild + restart)
ansible-playbook -i inventory.yml deploy-mcp-hub.yml --tags update

# Deploy to specific group
ansible-playbook -i inventory.yml deploy-mcp-hub.yml --limit servers

该 playbook 执行以下操作：

安装 Node.js 20 (如果尚未安装)
创建一个专用的 mcp-hub 系统用户
复制并构建项目
从你的 Ansible 变量中写入 .env 配置
安装并启动一个 systemd 服务 (失败时自动重启)

inventory.yml 中的主机变量允许你为不同的机器组配置不同的允许域名、日志级别和路径。

添加新服务器

查看 docs/adding-a-new-server.template.ts 获取带有注释的完整模板。

简而言之：

// 1. Create packages/server-myservice/src/my-server.ts
export class MyServer extends BaseMCPServer {
  constructor(options: MyOptions) {
    super(SERVER_INFO, options);
    this.registerTool("my_tool", this.handleMyTool.bind(this));
  }
  private async handleMyTool(args) {
    return this.ok({ result: "done" });
  }
}

// 2. Register in host/src/cli.ts
hub.use(new MyServer({ apiKey: process.env.MY_API_KEY! }));

创意：server-slack, server-postgres, server-docker, server-ansible, server-ssh, server-jira

环境变量

变量	默认值	描述
`MCP_DATA_DIR`	`./mcp-data`	所有中心数据的根目录
`MCP_FS_ROOT`	`./mcp-data/files`	文件系统沙盒根目录
`MCP_GIT_WORKSPACE`	`./mcp-data/repos`	Git 仓库基础路径
`MCP_MEMORY_PATH`	`./mcp-data/memory.json`	内存存储文件
`MCP_FETCH_ALLOWED_DOMAINS`	(空 = 全部)	逗号分隔的域名白名单
`MCP_LOG_LEVEL`	`info`	`debug	info	warn	error`

安全说明

文件系统：严格沙盒化。路径遍历攻击会返回错误，而不是数据。
Git：只读。不暴露 commit、push 或 clone 操作。
抓取：可选的域名白名单可防止对内部服务的 SSRF 攻击。
Systemd 服务：以非 root 用户身份运行，并设置了 PrivateTmp=true 和 NoNewPrivileges=true。

要求

Node.js ≥ 18 (用于原生 fetch API)
Git (用于 server-git)
带有 systemd 的 Linux (用于 Ansible 部署)

mcp-tool-hub