内容
# MCP 服务器集合
> 五个**生产级别**的 [模型上下文协议](https://modelcontextprotocol.io) 服务器 — TypeScript **和** Python — 带有类型化的工具模式（Zod / Pydantic），
> 标准输入输出 + HTTP 传输，**默认模拟后端** （所以它们在没有任何凭证的情况下运行），测试，以及 npm / PyPI 发布管道。
<!-- Badges placeholder: test · publish-npm · publish-pypi · license -->
---
## 目录
- [服务器](#服务器)
- [为什么它是生产级别的](#为什么它是生产级别的)
- [前提条件](#前提条件)
- [安装和运行](#安装和运行)
- [在 Claude Desktop 中使用](#在-claude-desktop-中使用)
- [在代理框架中使用](#在代理框架中使用)
- [传输和身份验证](#传输和身份验证)
- [连接真实后端](#连接真实后端)
- [测试](#测试)
- [发布](#发布)
- [仓库布局](#仓库布局)
- [故障排除](#故障排除)
## 服务器
| 软件包 | 语言 | 模块 / 构建 | 工具 |
|---------|------|----------------|-------|
| [`postgres-pgvector`](packages/postgres-pgvector) | Python | `pgvector_mcp.server` | `semantic_search` `sql_query` `vector_upsert` |
| [`bedrock-tools`](packages/bedrock-tools) | Python | `bedrock_mcp.server` | `invoke_claude` `invoke_llama` `knowledge_base_retrieve` `agent_invoke` |
| [`foundry-tools`](packages/foundry-tools) | Python | `foundry_mcp.server` | `foundry_chat` `foundry_search` `foundry_agent_run` |
| [`confluence-jira`](packages/confluence-jira) | TypeScript | `@mcpc/confluence-jira` | `search_pages` `read_page` `create_page` `search_issues` `create_issue` `transition_issue` |
| [`hotel-crm`](packages/hotel-crm) | TypeScript | `@mcpc/hotel-crm` | `search_reservations` `get_guest_profile` `list_loyalty_rewards` |
每个服务器**开箱即用，零凭证运行** （模拟后端） — 尝试，测试，并在连接真实内容之前演示。
## 为什么它是生产级别的
- **类型化的工具模式** — Zod（TypeScript）/ Pydantic（Python）；无非类型化输入。
- **两种传输方式** — `stdio`（Claude Desktop，本地代理）和 **HTTP** （可流式传输的 HTTP / SSE），带有远程使用的 bearer-token 检查。
- **后端接口** — 默认模拟，配置真实后端。
- **经过测试** — 针对模拟后端的单元测试；MCP Inspector 可验证。
- **可组合** — `examples/` 将服务器组合到 LangGraph 和 Semantic Kernel 中。
- **可发布** — npm（provenance）+ PyPI（Trusted Publishing）。
完整设计 + 惯例： [docs/architecture.md](docs/architecture.md) ·
[添加服务器](docs/adding-a-server.md) · [部署](docs/deployment.md)。
## 前提条件
- **Python 3.12+** 用于 Python 服务器。
- **Node 20+** 和 **pnpm 11+** (`npm install -g pnpm`) 用于 TypeScript 服务器。
## 安装和运行
### Python 服务器
```bash
cd packages/postgres-pgvector
python -m venv .venv && source .venv/bin/activate # Windows: .venv\Scripts\activate
pip install -e ".[dev]"
python -m pgvector_mcp.server # 通过 stdio 讲话（模拟后端）
```
相同的模式适用于 `bedrock-tools` (`bedrock_mcp.server`) 和
`foundry-tools` (`foundry_mcp.server`).
### TypeScript 服务器
```bash
pnpm install # 从仓库根目录
pnpm --filter @mcpc/confluence-jira build
node packages/confluence-jira/dist/server.js # stdio（模拟后端）
```
## 在 Claude Desktop 中使用
将服务器添加到 `claude_desktop_config.json` （macOS：
`~/Library/Application Support/Claude/`, Windows: `%APPDATA%\Claude\`):
```json
{
"mcpServers": {
"pgvector": { "command": "python", "args": ["-m", "pgvector_mcp.server"] },
"confluence-jira": {
"command": "node",
"args": ["/abs/path/packages/confluence-jira/dist/server.js"]
}
}
}
```
完整组合配置： [examples/claude-desktop-config](examples/claude-desktop-config).
## 在代理框架中使用
- **LangGraph** （通过 `langchain-mcp-adapters`）： [examples/langgraph-integration](examples/langgraph-integration)
- **Semantic Kernel** （通过 `MCPStdioPlugin`）： [examples/semantic-kernel](examples/semantic-kernel)
两者都将多个服务器组合成一个代理，针对模拟后端。
## 传输和身份验证
- **stdio** （默认）— 信任启动进程；无网络身份验证。
- **HTTP** — Python： `MCP_TRANSPORT=http python -m <pkg>.server` （可流式传输的 HTTP / SSE）。TS 服务器自带 bearer-token 检查 (`src/auth.ts`) 用于 HTTP 路径。始终在生产环境中将 HTTP 前置于 TLS + bearer/OAuth2 token。
使用 MCP Inspector 验证任何服务器：
`npx @modelcontextprotocol/inspector python -m pgvector_mcp.server`.
## 连接真实后端
每个服务器的工具逻辑都调用一个 `Backend` 接口，其默认值为模拟后端。
通过配置实现接口以对抗真实服务并选择它：
| 服务器 | 额外 | 真实后端 |
|--------|-------|--------------|
| postgres-pgvector | `[postgres]` | asyncpg + pgvector |
| bedrock-tools | `[aws]` | boto3 (bedrock-runtime / agent-runtime) |
| foundry-tools | `[azure]` | Azure OpenAI + Azure AI Search |
| confluence-jira | — | Atlassian REST (token + base URL) |
## 测试
```bash
# Python（每个包）
pytest packages/postgres-pgvector --cov --cov-report=term-missing
# TypeScript（所有工作区包）
pnpm -r build && pnpm -r test
```
Python 服务器覆盖率 100%；TS 服务器使用 `tsc` 构建干净，并通过 vitest。CI 运行两者（`.github/workflows/test.yml`）。
## 发布
- **npm** （TypeScript）：推送 `ts-v*` 标签 → `publish-npm.yml` 构建，测试，发布
具有 provenance (`NPM_TOKEN` 机密)。
- **PyPI** （Python）：推送 `py-v*` 标签 → `publish-pypi.yml` 构建每个包并
通过 Trusted Publishing 发布（OIDC，无存储令牌）。
## 仓库布局
```
packages/
├── postgres-pgvector/ # Python (FastMCP)
├── bedrock-tools/ # Python
├── foundry-tools/ # Python
├── confluence-jira/ # TypeScript (@modelcontextprotocol/sdk)
└── hotel-crm/ # TypeScript
examples/ # Claude Desktop, LangGraph, Semantic Kernel
docs/ # architecture, adding-a-server, deployment
pnpm-workspace.yaml # TS 工作区
```
## 故障排除
- **`pnpm install` 错误关于忽略的构建脚本（esbuild）** — 已经
通过 `pnpm-workspace.yaml` 中的 `onlyBuiltDependencies` 处理；如果您在
新克隆时遇到它，请再次运行 `pnpm install` 或 `pnpm rebuild esbuild`.
- **Python 服务器“模块未找到”** — 首先安装该包
(`pip install -e ".[dev]"` 在其目录内).
## 许可证
MIT (查看 [LICENSE](LICENSE)).
