项目简介

'@civic/mcp-tools' 是一个 monorepo (单一代码仓库)，包含多个基于 Model Context Protocol (MCP) 构建的应用组件。其核心是一个代理MCP服务器（'@civic/passthrough-mcp-server'），它可以连接到另一个目标MCP服务器，并向客户端暴露其工具。在请求和响应通过代理服务器时，可以插入**Hook（钩子）**来拦截、修改或过滤数据流，实现审计、安全、解释等功能。此外，仓库中还包含了一些示例性的MCP服务器，例如 '@civic/fetch-docs'，它是一个独立的MCP服务器，用于抓取网页内容。

主要功能点

Passthrough MCP Server (代理服务器):
- 作为MCP客户端和目标MCP服务器之间的中间层。
- 向连接它的MCP客户端暴露目标MCP服务器的工具。
- 支持配置 Hook 服务，在工具调用请求发送给目标服务器前、以及收到响应后进行处理。
- 支持多种传输协议（HTTP Stream, SSE, Stdio）。
- 管理与目标服务器的会话。
MCP Hooks (扩展钩子):
- 一套独立的微服务，通过 tRPC 协议与 Passthrough 服务器通信。
- 提供标准的 Hook 接口 ('@civic/hook-common') 用于处理工具调用请求和响应。
- 仓库中提供了审计 ('@civic/audit-hook')、安全过滤 ('@civic/guardrail-hook')、添加解释参数 ('@civic/explain-hook') 等示例 Hook 实现。
Fetch Docs MCP Server (网页抓取工具):
- 一个独立的、简单的MCP服务器示例。
- 实现了一个名为 'fetch' 的工具，可以根据提供的 URL 抓取网页内容并转换为 Markdown 格式。
- 可作为 Passthrough 服务器的目标服务器进行测试。

安装步骤

克隆仓库：

git clone https://github.com/civicteam/mcp-tools.git
cd mcp-tools

安装依赖（使用 pnpm）：
```
pnpm install
```
构建所有包：
```
pnpm build
```

服务器配置（面向 MCP 客户端）

MCP 客户端需要配置连接到 Passthrough 服务器。Passthrough 服务器本身需要通过环境变量配置它要连接的目标 MCP 服务器以及需要加载的 Hook 服务。

以下是 MCP 客户端连接到此 Passthrough 服务器的两种典型配置方式示例：

通过 Stdio 连接 (推荐用于开发和测试):

{
  "serverName": "passthrough-server",
  "type": "stdio",
  "command": "pnpm",
  "args": ["start", "--filter", "passthrough-mcp-server", "--stdio"]
}

'serverName': 给服务器起的别名。
'type': 连接类型，这里使用 'stdio'。
'command': 启动 Passthrough 服务器进程的命令。这里使用 pnpm 在仓库根目录启动 passthrough-mcp-server 包，并指定 stdio 模式。
'args': 传递给命令的参数。

通过 HTTP Stream 连接:

Passthrough 服务器默认运行在 HTTP Stream 模式下，端口 34000。

{
  "serverName": "passthrough-server",
  "type": "httpStream",
  "url": "http://localhost:34000/stream"
}

'serverName': 给服务器起的别名。
'type': 连接类型，这里使用 'httpStream'。
'url': Passthrough 服务器的 HTTP Stream 端点 URL。

Passthrough 服务器自身配置:

在启动 Passthrough 服务器进程前，需要设置环境变量指定目标服务器和Hook服务：

# 指定目标MCP服务器的URL (Fetch Docs示例默认在33003端口)
export TARGET_SERVER_URL="http://localhost:33003/stream"
# 可选：指定 Hook 服务的URL列表，用逗号分隔 (例如：审计、安全过滤、解释 Hook)
export HOOKS="http://localhost:33004,http://localhost:33005,http://localhost:33007" 
# 如果使用 STDIO 模式启动 passthrough 服务器，则不需要指定 PORT
# 如果使用 HTTP STREAM 模式，可以通过 PORT 环境变量修改端口，默认为 34000
# export PORT=34000

基本使用方法

根据需要，在单独的终端中启动目标 MCP 服务器（例如，Fetch Docs 服务器）。在仓库根目录执行：

pnpm start --filter fetch-docs --stdio 
# 或使用默认 HTTP Stream 模式:
# pnpm start --filter fetch-docs

（可选）根据需要，在单独的终端中启动一个或多个 Hook 服务。例如启动 Audit Hook：

cd packages/audit-hook
# 如果需要PostgreSQL审计，请先运行 setup-db 脚本并设置 POSTGRES_URL 环境变量
# pnpm setup-db
# export POSTGRES_URL="<your_postgres_url>"
pnpm start

重复此步骤启动 Guardrail Hook ('packages/guardrail-hook')、Explain Hook ('packages/explain-hook') 等。请注意它们默认监听的不同端口（见各自的 'src/index.ts' 文件）。

在设置好 'TARGET_SERVER_URL' 和可选的 'HOOKS' 环境变量后，在仓库根目录启动 Passthrough MCP 服务器：

pnpm start --filter passthrough-mcp-server --stdio 
# 或使用默认 HTTP Stream 模式:
# pnpm start --filter passthrough-mcp-server

配置你的 MCP 客户端，使其连接到刚刚启动的 Passthrough MCP 服务器（参考“服务器配置”部分）。
通过 MCP 客户端与 Passthrough 服务器交互，调用目标服务器暴露的工具。请求和响应将通过配置的 Hook 进行处理。

关键词

项目简介

主要功能点

安装步骤

服务器配置（面向 MCP 客户端）

基本使用方法

更多信息

信息