# https://github.com/mcparmory/registry 项目说明书
生成时间：2026-05-27 13:20:18 UTC
## 目录
- [项目介绍](#page-introduction)
- [服务器分类索引](#page-categories)
- [服务器标准模式](#page-server-pattern)
- [认证机制详解](#page-authentication)
- [部署指南](#page-deployment)
- [配置参考](#page-configuration)
- [故障排除](#page-troubleshooting)
- [贡献指南](#page-contributing)
## 项目介绍
### 相关页面
相关主题：[服务器分类索引](#page-categories), [服务器标准模式](#page-server-pattern)
相关源码文件
以下源码文件用于生成本页说明：
- [README.md](https://github.com/mcparmory/registry/blob/main/README.md)
- [servers/perplexity/server.json](https://github.com/mcparmory/registry/blob/main/servers/perplexity/server.json)
- [servers/perplexity/server.py](https://github.com/mcparmory/registry/blob/main/servers/perplexity/server.py)
- [servers/perplexity/_models.py](https://github.com/mcparmory/registry/blob/main/servers/perplexity/_models.py)
- [servers/e2b/server.json](https://github.com/mcparmory/registry/blob/main/servers/e2b/server.json)
- [servers/atlassian-confluence/server.py](https://github.com/mcparmory/registry/blob/main/servers/atlassian-confluence/server.py)
- [servers/atlassian-confluence/_auth.py](https://github.com/mcparmory/registry/blob/main/servers/atlassian-confluence/_auth.py)
- [servers/google-search-console/server.py](https://github.com/mcparmory/registry/blob/main/servers/google-search-console/server.py)
- [servers/github/_auth.py](https://github.com/mcparmory/registry/blob/main/servers/github/_auth.py)
- [servers/posthog/_auth.py](https://github.com/mcparmory/registry/blob/main/servers/posthog/_auth.py)
# 项目介绍
## 概述
**mcparmory/registry** 是一个开源的 MCP (Model Context Protocol) 服务器注册表仓库，托管在 GitHub 上，旨在为 AI Agent 提供统一管理的工具集成解决方案。该项目通过标准化的 MCP 服务器实现，让 AI Agent 能够以一致的方式调用外部服务和 API，从而避免在 Agent 上下文 (context) 中堆积大量配置信息导致的"上下文膨胀"问题。
资料来源：[README.md](https://github.com/mcparmory/registry/blob/main/README.md)
## 核心价值与定位
在现代 AI Agent 应用开发中，一个常见的痛点是需要为 Agent 配置大量的外部工具和 API 连接。这些配置通常以 MEMORY.md 或类似文件的形式存在，随着工具数量的增加，导致 Agent 的上下文窗口被大量占用，严重影响推理效率和成本。
mcparmory/registry 项目通过以下方式解决这一问题：
| 核心价值 | 说明 |
|---------|------|
| **标准化封装** | 所有服务器遵循统一的 MCP 协议规范 |
| **本地注册表** | 提供本地的 MCP 服务器注册表，无需依赖外部服务 |
| **多运行时支持** | 支持 uvx、docker 等多种运行时环境 |
| **开箱即用** | 通过简单的配置即可快速集成到 AI Agent 中 |
资料来源：[servers/perplexity/server.json](https://github.com/mcparmory/registry/blob/main/servers/perplexity/server.json)
## 架构设计
### 整体架构
MCP 服务器注册表采用分层架构设计，核心组件包括：
```mermaid
graph TD
A[AI Agent] --> B[MCP Client]
B --> C[Registry 注册表]
C --> D[Server Configuration]
D --> E{MCP Server}
E --> F[perplexity]
E --> G[github]
E --> H[confluence]
E --> I[e2b]
E --> J[其他服务器...]
F --> K[外部 API 服务]
G --> L[GitHub API]
H --> M[Atlassian API]
I --> N[E2B Sandboxes]
```
### 服务器目录结构
每个 MCP 服务器在 `servers/` 目录下独立存在，形成统一的目录结构：
```mermaid
graph LR
A[servers/] --> B[perplexity/]
A --> C[github/]
A --> D[confluence/]
A --> E[...其他]
B --> B1[server.json]
B --> B2[server.py]
B --> B3[_models.py]
B --> B4[_auth.py]
```
### 技术栈
| 组件 | 技术选型 | 说明 |
|-----|---------|------|
| MCP 框架 | FastMCP | 核心服务器框架 |
| 数据验证 | Pydantic | 请求/响应模型验证 |
| HTTP 客户端 | httpx | 异步 HTTP 请求处理 |
| 代码生成 | MCP Blacksmith | 从 OpenAPI 规范生成服务器代码 |
| 运行时 | uvx / Docker | 服务器执行环境 |
资料来源：[servers/perplexity/server.py:1-30](https://github.com/mcparmory/registry/blob/main/servers/perplexity/server.py)
## 服务器类型
### 搜索与信息获取类
| 服务器名称 | 版本 | 说明 | 运行时 |
|-----------|------|------|--------|
| perplexity | 1.0.2 | 网页搜索、AI 响应生成、嵌入向量创建 | uvx / docker |
| google-search-console | 1.0.3 | Google 搜索控制台数据访问 | uvx / docker |
| linkup | 1.0.2 | 网页抓取与来源结果搜索 | uvx / docker |
| firecrawl | - | 网站内容提取与 LLMs.txt 生成 | uvx / docker |
| parallel | 1.0.2 | 分布式任务执行与自动化 | uvx / docker |
资料来源：[servers/perplexity/server.json](https://github.com/mcparmory/registry/blob/main/servers/perplexity/server.json)、[servers/google-search-console/server.py](https://github.com/mcparmory/registry/blob/main/servers/google-search-console/server.py)
### 协作与内容管理类
| 服务器名称 | 版本 | 说明 | 认证方式 |
|-----------|------|------|----------|
| atlassian-confluence | 1.0.8 | Confluence 空间与页面管理 | OAuth2 |
| github | - | GitHub 仓库、Issue、PR 管理 | OAuth2 / PersonalAccessToken |
| canvas | - | LMS 学习管理系统集成 | OAuth2 |
资料来源：[servers/atlassian-confluence/server.py:1-40](https://github.com/mcparmory/registry/blob/main/servers/atlassian-confluence/server.py)
### 开发运维类
| 服务器名称 | 版本 | 说明 |
|-----------|------|------|
| pagerduty | 1.0.2 | 事件管理、值班调度、告警通知 |
| launchdarkly | - | 功能开关、部署分析 |
| posthog | - | 产品分析、事件追踪 |
资料来源：[servers/pagerduty/server.json](https://github.com/mcparmory/registry/blob/main/servers/pagerduty/server.json)
### AI 与安全类
| 服务器名称 | 版本 | 说明 |
|-----------|------|------|
| e2b | 1.0.5 | AI Agent 代码执行的安全沙箱环境 |
| ragie | - | 文档检索与 RAG 管道管理 |
资料来源：[servers/e2b/server.json](https://github.com/mcparmory/registry/blob/main/servers/e2b/server.json)
## 服务器配置格式
### server.json 配置结构
每个 MCP 服务器都包含一个标准化的 `server.json` 配置文件，遵循 MCP 协议规范：
```json
{
"$schema": "https://static.modelcontextprotocol.io/schemas/2025-12-11/server.schema.json",
"name": "com.mcparmory/perplexity",
"description": "Search the web, generate AI responses...",
"version": "1.0.2",
"repository": {
"url": "https://github.com/mcparmory/registry",
"source": "github"
},
"packages": [
{
"registryType": "pypi",
"identifier": "mcparmory-perplexity",
"version": "1.0.2",
"runtimeHint": "uvx",
"transport": {
"type": "stdio"
}
},
{
"registryType": "oci",
"identifier": "ghcr.io/mcparmory/perplexity:1.0.2",
"runtimeHint": "docker",
"transport": {
"type": "stdio"
}
}
]
}
```
资料来源：[servers/perplexity/server.json](https://github.com/mcparmory/registry/blob/main/servers/perplexity/server.json)
### 配置字段说明
| 字段 | 类型 | 必需 | 说明 |
|-----|------|------|------|
| name | string | 是 | 服务器唯一标识符，遵循反向域名格式 |
| description | string | 是 | 服务器功能描述 |
| version | string | 是 | 语义化版本号 |
| packages | array | 是 | 可用包列表 |
| packages[].registryType | string | 是 | 注册表类型：pypi 或 oci |
| packages[].identifier | string | 是 | 包标识符 |
| packages[].runtimeHint | string | 是 | 推荐运行时：uvx 或 docker |
| packages[].transport.type | string | 是 | 传输协议类型 |
## 认证机制
### 支持的认证类型
MCP 服务器通过 `_auth.py` 模块实现灵活的认证机制：
| 认证类型 | 适用场景 | 配置方式 |
|---------|---------|---------|
| OAuth2 | 需要用户授权的服务 | 环境变量 / .env 文件 |
| PersonalAPIKeyAuth | API Key 认证 | 环境变量 |
| PersonalAccessToken | GitHub 等平台 | 环境变量 |
| ApiKey | 通用 API Key | 环境变量 |
| BearerAuth | Token 认证 | 环境变量 |
资料来源：[servers/atlassian-confluence/_auth.py](https://github.com/mcparmory/registry/blob/main/servers/atlassian-confluence/_auth.py)
### 认证配置示例
```python
# 服务端使用 dotenv 加载环境变量
try:
from dotenv import load_dotenv
_env_path = Path(__file__).parent / '.env'
if _env_path.exists():
load_dotenv(_env_path)
except ImportError:
pass
```
服务器启动时自动从 `.env` 文件或环境变量中读取认证凭据。
资料来源：[servers/perplexity/server.py:28-35](https://github.com/mcparmory/registry/blob/main/servers/perplexity/server.py)
## 数据模型
### 模型层架构
服务器使用 Pydantic 定义严格的数据模型，确保 API 请求和响应的类型安全：
```mermaid
graph TD
A[_models.py] --> B[Request Models]
A --> C[Response Models]
A --> D[Internal Models]
B --> B1[StrictModel]
B --> B2[PermissiveModel]
C --> C1[ToolResult]
D --> D1[Config Models]
```
### 模型类型
| 模型类型 | 用途 | 验证策略 |
|---------|------|---------|
| StrictModel | 严格验证，抛出详细的 Pydantic 错误 | 拒绝未知字段 |
| PermissiveModel | 宽松验证，允许额外字段通过 | 忽略未知字段 |
```python
from _validators import StrictModel
from pydantic import Field
class ChatCompletionsChatCompletionsPostRequestBodyWebSearchOptionsUserLocation(StrictModel):
latitude: float | None = Field(default=None, description="纬度坐标")
longitude: float | None = Field(default=None, description="经度坐标")
country: str | None = Field(default=None, description="ISO 3166-1 国家代码")
```
资料来源：[servers/perplexity/_models.py:1-35](https://github.com/mcparmory/registry/blob/main/servers/perplexity/_models.py)
## 工具定义模式
### 工具装饰器
每个 MCP 工具使用 `@mcp.tool()` 装饰器定义，包含元数据注解：
```python
@mcp.tool(
title="搜索网页",
annotations=ToolAnnotations(
readOnlyHint=True,
openWorldHint=True
),
)
async def search_web(
query: str = Field(..., description="搜索查询字符串"),
max_results: int | None = Field(None, description="最大结果数量")
) -> dict[str, Any] | ToolResult:
"""工具功能描述文档字符串"""
# 实现逻辑
pass
```
### 工具注解说明
| 注解 | 类型 | 说明 |
|-----|------|------|
| readOnlyHint | bool | 提示工具是否只读操作 |
| openWorldHint | bool | 提示工具是否访问外部世界 |
资料来源：[servers/atlassian-confluence/server.py](https://github.com/mcparmory/registry/blob/main/servers/atlassian-confluence/server.py)
## HTTP 客户端配置
### 连接池管理
服务器使用 httpx 实现高性能异步 HTTP 通信：
```python
# 连接池配置
CONNECTION_POOL_SIZE = int(os.getenv("CONNECTION_POOL_SIZE", "100"))
MAX_KEEPALIVE_CONNECTIONS = int(os.getenv("MAX_KEEPALIVE_CONNECTIONS", "20"))
# 超时配置
HTTPX_TIMEOUT = httpx.Timeout(
connect=30.0,
read=60.0,
write=30.0,
pool=10.0
)
```
| 配置项 | 默认值 | 说明 |
|-------|-------|------|
| CONNECTION_POOL_SIZE | 100 | 最大连接池大小 |
| MAX_KEEPALIVE_CONNECTIONS | 20 | 保活连接数 |
| HTTPX_TIMEOUT | 见配置 | 请求超时设置 |
资料来源：[servers/google-search-console/server.py:35-50](https://github.com/mcparmory/registry/blob/main/servers/google-search-console/server.py)
## 部署方式
### uvx 运行时部署
通过 uvx 直接运行 PyPI 包：
```bash
uvx mcparmory-perplexity
```
### Docker 运行时部署
通过容器镜像运行：
```bash
docker run ghcr.io/mcparmory/perplexity:1.0.2
```
### 环境变量配置
| 环境变量 | 说明 | 示例 |
|---------|------|------|
| BASE_URL | API 基础 URL | https://api.perplexity.ai |
| LOG_LEVEL | 日志级别 | DEBUG, INFO, WARNING, ERROR |
| CONNECTION_POOL_SIZE | 连接池大小 | 100 |
| MCP_SERVER_* | 服务器特定配置 | MCP_SERVER_YOUR_DOMAIN |
## 常见使用场景
### 场景一：AI Agent 搜索增强
AI Agent 可以通过 perplexity 或 google-search-console 服务器实现实时网页搜索能力：
```mermaid
sequenceDiagram
participant Agent as AI Agent
participant MCP as MCP Client
participant Search as Search Server
participant API as External API
Agent->>MCP: search_web(query="最新AI新闻")
MCP->>Search: 调用工具
Search->>API: HTTP Request
API-->>Search: Search Results
Search-->>MCP: ToolResult
MCP-->>Agent: 结构化结果
```
### 场景二：开发者工具集成
通过 github 服务器实现仓库管理和自动化工作流：
```mermaid
sequenceDiagram
participant Agent as AI Agent
participant MCP as MCP Client
participant GitHub as GitHub Server
Agent->>MCP: create_pull_request()
MCP->>GitHub: 调用工具
GitHub-->>Agent: PR 创建结果
```
### 场景三：安全代码执行
通过 e2b 服务器在隔离沙箱中安全执行 AI 生成的代码：
```python
# 使用 e2b 服务器执行代码
result = await e2b_sandbox.execute(code="print('Hello World')")
```
## 版本兼容性
| 服务器名称 | 当前版本 | MCP 协议版本 |
|-----------|---------|-------------|
| perplexity | 1.0.2 | 2025-12-11 |
| google-search-console | 1.0.3 | 2025-12-11 |
| e2b | 1.0.5 | 2025-12-11 |
| atlassian-confluence | 1.0.8 | 2025-12-11 |
所有服务器遵循统一的 MCP 协议 schema 版本，确保跨服务器的一致性和兼容性。
## 与社区的关系
根据 Reddit 社区讨论，本项目解决了 AI Agent 开发中的关键痛点：
> "Stop bloating your agent context with MEMORY.md. I built a local registry..."
本注册表项目作为开源替代方案，让开发者可以在本地管理 MCP 服务器，避免依赖外部服务，同时减少 Agent 上下文的膨胀问题。
资料来源：[Reddit 社区讨论](https://www.reddit.com/r/OpenAI/comments/1t1pfqo/stop_bloating_your_agent_context_with_memorymd_i/)
## 参与贡献
### 添加新服务器
1. 在 `servers/` 目录下创建新服务器目录
2. 添加 `server.json` 配置文件
3. 使用 MCP Blacksmith 生成服务器代码
4. 实现 `_auth.py` 认证模块
5. 测试并提交 PR
### 代码规范
- 使用 Pydantic StrictModel 进行数据验证
- 遵循 PEP 8 代码风格
- 所有工具函数使用 async/await
- 提供完整的中英文文档字符串
## 参见
- [MCP 协议规范](https://modelcontextprotocol.io/)
- [FastMCP 框架](https://github.com/jlowin/fastmcp)
- [MCP Blacksmith 代码生成器](https://mcpblacksmith.com/)
- [官方服务器注册表](https://github.com/modelcontextprotocol/servers)
---
## 服务器分类索引
### 相关页面
相关主题：[项目介绍](#page-introduction), [部署指南](#page-deployment)
相关源码文件
以下源码文件用于生成本页说明：
- [README.md](https://github.com/mcparmory/registry/blob/main/README.md)
- [servers/perplexity/server.json](https://github.com/mcparmory/registry/blob/main/servers/perplexity/server.json)
- [servers/perplexity/server.py](https://github.com/mcparmory/registry/blob/main/servers/perplexity/server.py)
- [servers/perplexity/_models.py](https://github.com/mcparmory/registry/blob/main/servers/perplexity/_models.py)
- [servers/linkup/server.json](https://github.com/mcparmory/registry/blob/main/servers/linkup/server.json)
- [servers/e2b/server.json](https://github.com/mcparmory/registry/blob/main/servers/e2b/server.json)
- [servers/e2b/server.py](https://github.com/mcparmory/registry/blob/main/servers/e2b/server.py)
- [servers/google-search-console/server.py](https://github.com/mcparmory/registry/blob/main/servers/google-search-console/server.py)
- [servers/atlassian-confluence/server.json](https://github.com/mcparmory/registry/blob/main/servers/atlassian-confluence/server.json)
- [servers/atlassian-confluence/server.py](https://github.com/mcparmory/registry/blob/main/servers/atlassian-confluence/server.py)
- [servers/atlassian-confluence/_models.py](https://github.com/mcparmory/registry/blob/main/servers/atlassian-confluence/_models.py)
- [servers/posthog/_auth.py](https://github.com/mcparmory/registry/blob/main/servers/posthog/_auth.py)
- [servers/ragie/_models.py](https://github.com/mcparmory/registry/blob/main/servers/ragie/_models.py)
- [servers/launchdarkly/_auth.py](https://github.com/mcparmory/registry/blob/main/servers/launchdarkly/_auth.py)
- [servers/canvas/_auth.py](https://github.com/mcparmory/registry/blob/main/servers/canvas/_auth.py)
- [servers/pagerduty/server.json](https://github.com/mcparmory/registry/blob/main/servers/pagerduty/server.json)
- [servers/parallel/server.json](https://github.com/mcparmory/registry/blob/main/servers/parallel/server.json)
- [servers/contentful-management/_models.py](https://github.com/mcparmory/registry/blob/main/servers/contentful-management/_models.py)
- [servers/firecrawl/server.py](https://github.com/mcparmory/registry/blob/main/servers/firecrawl/server.py)
# 服务器分类索引
## 概述
mcparmory/registry 是一个开源的 MCP（Model Context Protocol）服务器注册中心，托管在 GitHub 上。该仓库汇集了多种第三方服务的 MCP 服务器实现，为 AI 代理提供标准化的工具调用接口。通过统一的注册机制，开发者可以快速发现、配置和部署所需的 MCP 服务器。
根据社区反馈，类似这样的本地注册中心可以帮助 AI Agent 避免上下文膨胀问题，使用本地配置文件替代在每次对话中传递 MEMORY.md 的方式。[Reddit - Stop bloating your agent context with MEMORY.md](https://www.reddit.com/r/OpenAI/comments/1t1pfqo/stop_bloating_your_agent_context_with_memorymd_i/)
## 架构设计
### 注册中心整体架构
```mermaid
graph TD
A[mcparmory/registry] --> B[服务器定义层]
A --> C[服务端实现层]
A --> D[认证模块层]
A --> E[数据模型层]
B --> B1[server.json 元数据]
B --> B2[schema 验证]
C --> C1[FastMCP 框架]
C --> C2[工具函数]
C --> C3[请求处理]
D --> D1[OAuth2 认证]
D --> D2[API Key 认证]
D --> D3[Personal API Key]
E --> E1[Pydantic 模型]
E --> E2[请求/响应验证]
```
### MCP 服务器运行时架构
```mermaid
graph LR
A[AI Agent] -->|STDIO 传输| B[MCP Server]
B --> C[第三方 API]
B --> D[_auth.py 认证模块]
B --> E[_models.py 数据模型]
B --> F[server.py 核心逻辑]
D --> C
F --> C
```
## 服务器分类
### 按功能分类
| 分类 | 服务器名称 | 版本 | 说明 |
|------|-----------|------|------|
| **搜索与信息获取** | perplexity | 1.0.2 | 网络搜索、AI 响应生成、实时信息嵌入 |
| | linkup | 1.0.2 | 网络搜索和页面抓取，提供来源追溯结果 |
| | perigon | 1.0.2 | 新闻文章、记者、公司信息搜索 |
| | google-search-console | 1.0.3 | Google 搜索控制台数据访问 |
| **内容管理** | atlassian-confluence | 1.0.8 | Atlassian Confluence 页面和空间管理 |
| | notion | (见 README) | Notion 工作区和页面操作 |
| | contentful-management | (见 README) | Contentful 内容管理 |
| **开发工具** | github | (见 README) | GitHub 代码仓库和操作 |
| | e2b | 1.0.5 | AI Agent 安全沙箱环境 |
| **数据与分析** | posthog | 1.0.2 | 产品分析、洞察、批量导出 |
| | ragie | (见 README) | 文档检索和 RAG 功能 |
| **自动化与工作流** | pagerduty | 1.0.2 | 事件管理、值班调度、告警通知 |
| | launchdarkly | (见 README) | 功能开关和发布策略管理 |
| | parallel | 1.0.2 | 分布式任务执行和自动化 |
| **学习平台** | canvas | (见 README) | LMS Canvas 课程和作业管理 |
| **内容生成** | firecrawl | (见 README) | LLMs.txt 文件生成 |
### 服务器标识符命名规范
所有服务器遵循反向域名命名约定：
```
com.mcparmory/{服务名}
```
| 服务器 | 完整标识符 |
|--------|-----------|
| Perplexity | `com.mcparmory/perplexity` |
| Linkup | `com.mcparmory/linkup` |
| E2B | `com.mcparmory/e2b` |
| PagerDuty | `com.mcparmory/pagerduty` |
| Parallel | `com.mcparmory/parallel` |
资料来源：[servers/perplexity/server.json:2](https://github.com/mcparmory/registry/blob/main/servers/perplexity/server.json)
## 服务端点与工具
### Perplexity 服务器工具
Perplexity MCP 服务器提供以下核心功能：
| 工具名称 | 功能描述 | 认证方式 |
|---------|---------|---------|
| create_chat_completion | 创建聊天补全 | API Key |
| search | 执行网络搜索 | API Key |
| create_async_chat_completion | 异步聊天补全 | API Key |
| embeddings | 生成文本嵌入 | API Key |
| contextual_embeddings | 上下文感知嵌入 | API Key |
资料来源：[servers/perplexity/_models.py:1-30](https://github.com/mcparmory/registry/blob/main/servers/perplexity/_models.py)
### E2B 沙箱服务器
E2B 服务器为 AI Agent 提供安全的代码执行环境：
| 工具名称 | 功能描述 |
|---------|---------|
| list_sandboxes | 列出所有沙箱实例 |
| create_sandbox | 创建新的沙箱环境 |
| execute_code | 在沙箱中执行代码 |
| manage_sandbox | 管理沙箱生命周期 |
```mermaid
graph TD
A[AI Agent] --> B[list_sandboxes]
A --> C[create_sandbox]
A --> D[execute_code]
B --> E[返回沙箱列表]
C --> F{沙箱状态}
F -->|running| G[可执行代码]
F -->|paused| H[暂停状态]
D --> I[代码执行结果]
D --> J[错误信息]
```
资料来源：[servers/e2b/server.py:1-50](https://github.com/mcparmory/registry/blob/main/servers/e2b/server.py)
### Confluence 服务器功能
Atlassian Confluence MCP 服务器提供丰富的文档管理功能：
| 功能模块 | 工具数量 | 主要操作 |
|---------|---------|---------|
| 页面管理 | 15+ | 创建、读取、更新、删除页面 |
| 标签管理 | 8 | 添加、移除、列出标签 |
| 空间管理 | 10+ | 空间 CRUD 操作 |
| 权限控制 | 12 | 用户和组权限管理 |
| 观看订阅 | 6 | 页面和空间通知管理 |
资料来源：[servers/atlassian-confluence/server.py:1-100](https://github.com/mcparmory/registry/blob/main/servers/atlassian-confluence/server.py)
## 认证机制
### 支持的认证类型
```mermaid
graph TD
A[MCP 服务器认证] --> B[OAuth2]
A --> C[API Key]
A --> D[Bearer Token]
A --> E[Personal API Key]
B --> B1[Canvas LMS]
C --> C1[LaunchDarkly]
C --> C2[PagerDuty]
D --> D1[多个服务]
E --> E1[PostHog]
```
### 认证配置示例
**PostHog 认证配置**（PersonalAPIKeyAuth）：
```python
"create_insight_sharing_password": [["PersonalAPIKeyAuth"]],
"list_insight_thresholds": [["PersonalAPIKeyAuth"]],
"get_insight": [["PersonalAPIKeyAuth"]],
"update_insight": [["PersonalAPIKeyAuth"]],
"annotations_destroy": [["PersonalAPIKeyAuth"]],
```
资料来源：[servers/posthog/_auth.py:1-30](https://github.com/mcparmory/registry/blob/main/servers/posthog/_auth.py)
**Canvas LMS 认证配置**（OAuth2 + Bearer）：
```python
"list_discussion_topics": [["OAuth2"], ["bearerAuth"]],
"get_discussion_topic": [["OAuth2"], ["bearerAuth"]],
"update_discussion_topic": [["OAuth2"], ["bearerAuth"]],
"list_assignment_due_dates": [["OAuth2"], ["bearerAuth"]],
```
资料来源：[servers/canvas/_auth.py:1-20](https://github.com/mcparmory/registry/blob/main/servers/canvas/_auth.py)
## 包分发配置
### server.json 结构
每个服务器都包含标准的 `server.json` 配置文件：
```json
{
"$schema": "https://static.modelcontextprotocol.io/schemas/2025-12-11/server.schema.json",
"name": "com.mcparmory/{服务名}",
"description": "服务描述",
"version": "1.0.x",
"repository": {
"url": "https://github.com/mcparmory/registry",
"source": "github"
},
"packages": [
{
"registryType": "pypi",
"identifier": "mcparmory-{服务名}",
"version": "1.0.x",
"runtimeHint": "uvx",
"transport": {
"type": "stdio"
}
},
{
"registryType": "oci",
"identifier": "ghcr.io/mcparmory/{服务名}:1.0.x",
"runtimeHint": "docker",
"transport": {
"type": "stdio"
}
}
]
}
```
资料来源：[servers/e2b/server.json:1-25](https://github.com/mcparmory/registry/blob/main/servers/e2b/server.json)
### 包类型对比
| 分发方式 | registryType | 运行时提示 | 适用场景 |
|---------|--------------|------------|---------|
| PyPI | `pypi` | `uvx` | Python 环境直接运行 |
| OCI | `oci` | `docker` | 容器化部署环境 |
### 传输协议
所有服务器统一使用 `stdio` 传输类型：
```mermaid
graph LR
A[主机进程] -->|stdin| B[MCP Server]
B -->|stdout| A
```
资料来源：[servers/linkup/server.json:15-20](https://github.com/mcparmory/registry/blob/main/servers/linkup/server.json)
## 数据模型
### Pydantic 模型架构
服务器使用 Pydantic 进行请求/响应数据验证：
```mermaid
classDiagram
class StrictModel {
<<基类>>
+严格字段验证
+必填字段检查
}
class PermissiveModel {
<<基类>>
+宽松字段验证
+可选字段处理
}
class *Request {
+path: PathParams
+query: QueryParams
+body: RequestBody
}
class *Response {
+数据验证
+类型转换
}
StrictModel <|-- *Request
PermissiveModel <|-- *Request
```
### 模型导出示例
```python
__all__ = [
"SearchArticlesRequest",
"SearchCompaniesRequest",
"SearchJournalistsRequest",
"SearchStoriesRequest",
"VectorSearchArticlesRequest",
]
```
资料来源：[servers/perigon/_models.py:1-25](https://github.com/mcparmory/registry/blob/main/servers/perigon/_models.py)
### Ragie 连接配置模型
```python
class CreateConnectionRequestBody(StrictModel):
"""创建新连接的请求体"""
name: str # 连接名称
description: str | None # 可选描述
metadata: dict[str, Any] | None # 元数据键值对
workflow: Literal["parse", "index"] | None # 处理工作流
connection: PublicBackblazeConnection | PublicGcsConnection | ...
partition_strategy: CreateConnectionRequestBodyPartitionStrategy | None
```
资料来源：[servers/ragie/_models.py:50-80](https://github.com/mcparmory/registry/blob/main/servers/ragie/_models.py)
## 快速入门
### 环境要求
| 组件 | 最低版本 | 推荐版本 |
|------|---------|---------|
| Python | 3.10+ | 3.12+ |
| uvx | 最新版 | 最新版 |
| Docker | 24.0+ | 最新版 |
### 安装方式
**方式一：通过 uvx 运行**
```bash
uvx mcparmory-{服务名}
```
**方式二：通过 Docker 运行**
```bash
docker run ghcr.io/mcparmory/{服务名}:{版本}
```
**方式三：pip 安装**
```bash
pip install mcparmory-{服务名}
```
### 环境配置
在服务器目录下创建 `.env` 文件：
```bash
# API 认证配置
PERPLEXITY_API_KEY=your-api-key
GOOGLE_API_KEY=your-google-key
# 服务端点配置
BASE_URL=https://api.example.com
# 连接池配置
CONNECTION_POOL_SIZE=100
MAX_KEEPALIVE_CONNECTIONS=20
# 日志级别
LOG_LEVEL=INFO
```
资料来源：[servers/google-search-console/server.py:1-50](https://github.com/mcparmory/registry/blob/main/servers/google-search-console/server.py)
## 常见故障排查
### 认证错误
| 错误类型 | 可能原因 | 解决方案 |
|---------|---------|---------|
| `401 Unauthorized` | API Key 过期或无效 | 检查环境变量配置 |
| `403 Forbidden` | 权限不足 | 确认账户权限设置 |
| `Missing Auth` | 未配置认证信息 | 添加对应的认证凭证 |
### 连接问题
| 错误类型 | 可能原因 | 解决方案 |
|---------|---------|---------|
| 连接超时 | 网络问题或服务不可用 | 检查网络连接和服务状态 |
| 连接池耗尽 | 并发请求过多 | 调整 `CONNECTION_POOL_SIZE` |
| 超时错误 | 请求处理时间过长 | 增加 `HTTPX_TIMEOUT` 配置 |
### 数据验证错误
```python
# Pydantic 验证错误示例
try:
_request = _models.GenerateLlMsTxtRequest(
body=_models.GenerateLlMsTxtRequestBody(
url=url,
max_urls=max_urls,
show_full_text=show_full_text
)
)
except pydantic.ValidationError as _validation_err:
logging.error(f"Parameter validation failed: {_validation_err}")
raise ValueError(f"Invalid parameters: {_validation_err.errors()}")
```
资料来源：[servers/firecrawl/server.py:40-55](https://github.com/mcparmory/registry/blob/main/servers/firecrawl/server.py)
## 扩展新的服务器
### 添加新服务器的步骤
```mermaid
graph TD
A[创建服务器目录] --> B[编写 server.json]
B --> C[编写 server.py]
C --> D[编写 _models.py]
D --> E[编写 _auth.py]
E --> F[测试部署]
F --> G[提交 Pull Request]
```
### 目录结构规范
```
servers/
└── {服务名}/
├── server.json # 元数据和包配置
├── server.py # 主服务端实现
├── _models.py # Pydantic 数据模型
├── _auth.py # 认证配置
├── _validators.py # 自定义验证器
└── README.md # 服务文档
```
## 版本兼容性
| 服务器 | 最低 Schema 版本 | 说明 |
|-------|-----------------|------|
| 所有服务器 | 2025-12-11 | 基于 modelcontextprotocol.io 标准 |
所有配置文件引用统一 schema：
```json
"$schema": "https://static.modelcontextprotocol.io/schemas/2025-12-11/server.schema.json"
```
资料来源：[servers/pagerduty/server.json:2](https://github.com/mcparmory/registry/blob/main/servers/pagerduty/server.json)
## 参考链接
| 资源 | 链接 |
|------|------|
| GitHub 仓库 | [mcparmory/registry](https://github.com/mcparmory/registry) |
| MCP 协议规范 | [Model Context Protocol](https://modelcontextprotocol.io) |
| FastMCP 框架 | [FastMCP](https://github.com/jlowin/fastmcp) |
| PyPI 分发包 | [mcparmory-*](https://pypi.org/search/?q=mcparmory) |
## 相关主题
- [服务器快速开始指南](快速开始)
- [认证配置详解](认证配置)
- [包分发机制](包分发)
- [贡献新服务器](贡献指南)
---
## 服务器标准模式
### 相关页面
相关主题：[项目介绍](#page-introduction), [认证机制详解](#page-authentication)
相关源码文件
以下源码文件用于生成本页说明：
- [servers/atlassian-confluence/server.py](https://github.com/mcparmory/registry/blob/main/servers/atlassian-confluence/server.py)
- [servers/perplexity/server.py](https://github.com/mcparmory/registry/blob/main/servers/perplexity/server.py)
- [servers/perplexity/server.json](https://github.com/mcparmory/registry/blob/main/servers/perplexity/server.json)
- [servers/perplexity/_models.py](https://github.com/mcparmory/registry/blob/main/servers/perplexity/_models.py)
- [servers/perplexity/_auth.py](https://github.com/mcparmory/registry/blob/main/servers/perplexity/_auth.py)
- [servers/e2b/server.py](https://github.com/mcparmory/registry/blob/main/servers/e2b/server.py)
- [servers/e2b/server.json](https://github.com/mcparmory/registry/blob/main/servers/e2b/server.json)
- [servers/linkup/server.json](https://github.com/mcparmory/registry/blob/main/servers/linkup/server.json)
- [servers/firecrawl/server.py](https://github.com/mcparmory/registry/blob/main/servers/firecrawl/server.py)
- [servers/google-search-console/server.py](https://github.com/mcparmory/registry/blob/main/servers/google-search-console/server.py)
- [servers/posthog/_auth.py](https://github.com/mcparmory/registry/blob/main/servers/posthog/_auth.py)
- [servers/launchdarkly/_auth.py](https://github.com/mcparmory/registry/blob/main/servers/launchdarkly/_auth.py)
- [servers/ragie/_models.py](https://github.com/mcparmory/registry/blob/main/servers/ragie/_models.py)
# 服务器标准模式
本文档介绍 MCP Registry 仓库中所有 MCP 服务器遵循的标准化实现模式。该模式确保了服务器之间的一致性、可维护性和可扩展性。
## 概述
MCP 服务器标准模式是一套统一的架构约定和实现规范，用于构建与 Model Context Protocol 兼容的服务器组件。每个服务器都遵循相同的项目结构、传输协议、认证机制和错误处理流程。
资料来源：[servers/perplexity/server.py:1-30](https://github.com/mcparmory/registry/blob/main/servers/perplexity/server.py)
## 核心架构
### 整体架构图
```mermaid
graph TB
subgraph "MCP 服务器标准模式"
A["FastMCP 框架"] --> B["工具层 Tools"]
A --> C["资源层 Resources"]
A --> D["提示层 Prompts"]
B --> E["认证模块 _auth.py"]
B --> F["模型模块 _models.py"]
E --> G["API 网关"]
F --> H["HTTPX 客户端"]
G --> H
end
I["MCP 客户端"] -->|stdio| A
J["外部 API"] <--> H
```
### 技术栈组件
| 组件 | 用途 | 配置文件 |
|------|------|----------|
| FastMCP | 服务器框架 | server.py |
| httpx | HTTP 客户端 | server.py |
| Pydantic | 数据验证 | _models.py, _validators.py |
| python-dotenv | 环境配置 | server.py |
| mcp.types | MCP 类型定义 | server.py |
资料来源：[servers/atlassian-confluence/server.py:39-52](https://github.com/mcparmory/registry/blob/main/servers/atlassian-confluence/server.py)
## 项目结构规范
每个 MCP 服务器遵循统一的项目目录结构：
```
servers//
├── server.py # 主服务器实现
├── server.json # 服务器元数据
├── _auth.py # 认证配置
├── _models.py # Pydantic 模型定义
├── _validators.py # 自定义验证器
├── pyproject.toml # Python 项目配置
├── .env # 环境变量（可选）
└── README.md # 文档说明
```
资料来源：[servers/perplexity/server.json](https://github.com/mcparmory/registry/blob/main/servers/perplexity/server.json)
## 服务器配置规范
### server.json 配置结构
每个服务器的 `server.json` 文件定义了其元数据和分发包信息：
```json
{
"$schema": "https://static.modelcontextprotocol.io/schemas/2025-12-11/server.schema.json",
"name": "com.mcparmory/",
"description": "服务器功能描述",
"version": "1.0.0",
"repository": {
"url": "https://github.com/mcparmory/registry",
"source": "github"
},
"packages": [
{
"registryType": "pypi",
"identifier": "mcparmory-",
"version": "1.0.0",
"runtimeHint": "uvx",
"transport": {
"type": "stdio"
}
},
{
"registryType": "oci",
"identifier": "ghcr.io/mcparmory/:1.0.0",
"runtimeHint": "docker",
"transport": {
"type": "stdio"
}
}
]
}
```
资料来源：[servers/perplexity/server.json](https://github.com/mcparmory/registry/blob/main/servers/perplexity/server.json)
### 配置参数说明
| 参数 | 类型 | 说明 | 示例值 |
|------|------|------|--------|
| name | string | 服务器唯一标识符 | "com.mcparmory/perplexity" |
| description | string | 功能描述 | "Search the web..." |
| version | string | 语义化版本 | "1.0.2" |
| registryType | string | 分发注册类型 | "pypi", "oci" |
| runtimeHint | string | 运行时提示 | "uvx", "docker" |
| transport.type | string | 传输协议 | "stdio" |
资料来源：[servers/e2b/server.json](https://github.com/mcparmory/registry/blob/main/servers/e2b/server.json)
## 服务器初始化模式
### 标准初始化流程
```mermaid
sequenceDiagram
participant S as Server.py
participant E as .env
participant F as FastMCP
participant M as Middleware
S->>E: 加载环境变量
E-->>S: 配置参数
S->>F: 创建 FastMCP 实例
S->>M: 配置中间件
S->>S: 设置连接池参数
S->>S: 配置日志级别
F->>F: 注册工具/资源/提示
F->>S: 服务器就绪
```
### 环境变量配置
所有服务器支持通过环境变量进行配置：
| 环境变量 | 默认值 | 说明 |
|----------|--------|------|
| BASE_URL | 服务商默认值 | API 基础地址 |
| LOG_LEVEL | "INFO" | 日志级别 |
| CONNECTION_POOL_SIZE | "100" | 连接池大小 |
| MAX_KEEPALIVE_CONNECTIONS | "20" | 最大保活连接数 |
| HTTPX_TIMEOUT | 60秒 | HTTP 超时时间 |
资料来源：[servers/perplexity/server.py:55-75](https://github.com/mcparmory/registry/blob/main/servers/perplexity/server.py)
### 核心初始化代码模式
```python
# 环境变量加载
try:
from dotenv import load_dotenv
_env_path = Path(__file__).parent / '.env'
if _env_path.exists():
load_dotenv(_env_path)
except ImportError:
pass
# 服务器配置
BASE_URL = os.getenv("BASE_URL", "https://api.perplexity.ai")
SERVER_NAME = "Perplexity AI"
SERVER_VERSION = "1.0.2"
CONNECTION_POOL_SIZE = int(os.getenv("CONNECTION_POOL_SIZE", "100"))
MAX_KEEPALIVE_CONNECTIONS = int(os.getenv("MAX_KEEPALIVE_CONNECTIONS", "20"))
# 日志配置
LOG_LEVEL = os.getenv("LOG_LEVEL", "INFO").upper()
if LOG_LEVEL not in ("DEBUG", "INFO", "WARNING", "ERROR"):
LOG_LEVEL = "INFO"
# HTTP 客户端超时配置
HTTPX_TIMEOUT = httpx.Timeout(...)
```
资料来源：[servers/google-search-console/server.py](https://github.com/mcparmory/registry/blob/main/servers/google-search-console/server.py)
## 认证机制
### 认证架构
每个服务器拥有独立的认证模块 `_auth.py`，定义操作级别的认证策略：
```mermaid
graph LR
A["工具调用"] --> B["_auth.py"]
B --> C{"认证类型"}
C -->|ApiKey| D["API Key 认证"]
C -->|OAuth2| E["OAuth2 认证"]
C -->|PersonalAPIKeyAuth| F["个人 API Key"]
C -->|BearerAuth| G["Bearer Token"]
D --> H["HTTP Headers"]
E --> I["Authorization Header"]
```
### 认证类型支持
| 认证类型 | 适用场景 | 配置方式 |
|----------|----------|----------|
| ApiKey | 简单的 API 密钥认证 | X-API-Key Header |
| OAuth2 | 需要 OAuth 流程 | 授权码/客户端凭证 |
| PersonalAPIKeyAuth | 个人访问令牌 | Authorization Header |
| BearerAuth | Bearer Token | Authorization: Bearer |
| BasicAuth | HTTP 基本认证 | Authorization: Basic |
资料来源：[servers/posthog/_auth.py:1-50](https://github.com/mcparmory/registry/blob/main/servers/posthog/_auth.py)
### 操作级认证配置
认证模块使用字典结构映射每个操作的认证方法：
```python
AUTH_CONFIG = {
"create_chat_completion": [["PersonalAPIKeyAuth"]],
"delete_insight_sharing_password": [["PersonalAPIKeyAuth"]],
"list_github_branches": [["PersonalAPIKeyAuth"]],
"create_batch_export": [["PersonalAPIKeyAuth"]],
# ... 更多操作映射
}
```
资料来源：[servers/launchdarkly/_auth.py:1-80](https://github.com/mcparmory/registry/blob/main/servers/launchdarkly/_auth.py)
## 工具定义模式
### 工具装饰器使用
所有工具通过 FastMCP 的 `@mcp.tool()` 装饰器定义：
```python
@mcp.tool(
title="工具标题",
annotations=ToolAnnotations(
readOnlyHint=True, # 是否只读操作
openWorldHint=True # 是否涉及外部世界
),
)
async def tool_name(
param: str = Field(..., description="参数说明"),
optional_param: int | None = Field(None, description="可选参数")
) -> dict[str, Any] | ToolResult:
"""工具功能描述"""
# 实现代码
```
资料来源：[servers/atlassian-confluence/server.py:200-280](https://github.com/mcparmory/registry/blob/main/servers/atlassian-confluence/server.py)
### 工具参数验证流程
```mermaid
graph TD
A["接收工具调用"] --> B["构建 Request 模型"]
B --> C{"Pydantic 验证"}
C -->|成功| D["提取 HTTP 参数"]
C -->|失败| E["抛出 ValidationError"]
D --> F["执行 HTTP 请求"]
E --> G["记录错误日志"]
G --> H["返回错误信息"]
F --> I{"API 响应"}
I -->|成功| J["返回 ToolResult"]
I -->|失败| K["异常处理"]
```
### 工具实现标准模板
```python
async def tool_name(
param: str = Field(..., description="必选参数描述"),
optional: str | None = Field(None, description="可选参数描述")
) -> dict[str, Any] | ToolResult:
"""工具功能的中文描述"""
# 1. 参数预处理
_param = param # 使用别名处理
# 2. 构建请求模型并验证
try:
_request = _models.SomeRequest(
body=_models.SomeRequestBody(param=_param)
)
except pydantic.ValidationError as _validation_err:
logging.error(f"参数验证失败: {_validation_err}")
raise ValueError(f"无效参数: {_validation_err.errors()}") from _validation_err
# 3. 提取 HTTP 参数
_http_path = "/api/endpoint"
_http_body = _request.body.model_dump(by_alias=True, exclude_none=True)
_http_headers = {}
# 4. 注入认证
_auth = await _get_auth_for_operation("operation_name")
# 5. 执行请求
_response_data, _ = await _execute_tool_request(
tool_name="tool_name",
method="POST",
path=_http_path,
request_id=_request_id,
headers=_http_headers,
)
# 6. 返回结果
return _response_data
```
资料来源：[servers/firecrawl/server.py](https://github.com/mcparmory/registry/blob/main/servers/firecrawl/server.py)
## 数据模型规范
### 模型定义模式
使用 Pydantic v2 定义请求和响应模型：
```python
from pydantic import Field
from _validators import StrictModel, PermissiveModel
class SomeRequestBody(StrictModel):
"""请求体模型说明"""
required_field: str = Field(..., description="必选字段说明")
optional_field: int | None = Field(None, description="可选字段说明")
model_config = {
"json_schema_extra": {...} # 可选的 JSON Schema 配置
}
class SomeResponseBody(PermissiveModel):
"""响应体模型说明"""
id: str = Field(..., alias="id", description="唯一标识符")
```
资料来源：[servers/perplexity/_models.py:1-60](https://github.com/mcparmory/registry/blob/main/servers/perplexity/_models.py)
### 验证器模式
| 验证器类型 | 说明 | 使用场景 |
|------------|------|----------|
| StrictModel | 严格验证模式 | 必选字段必须存在且类型正确 |
| PermissiveModel | 宽松验证模式 | 允许额外字段存在 |
资料来源：[servers/ragie/_models.py:1-50](https://github.com/mcparmory/registry/blob/main/servers/ragie/_models.py)
### 字段别名处理
```python
class RequestQuery(StrictModel):
# validation_alias: API 接收的参数名
# serialization_alias: 序列化时使用的名称
page_size: int | None = Field(
default=None,
validation_alias="pageSize",
serialization_alias="page_size",
description="分页大小参数"
)
```
## 工具注解说明
| 注解 | 类型 | 说明 |
|------|------|------|
| readOnlyHint | bool | 指示工具是否仅执行读取操作 |
| openWorldHint | bool | 指示工具是否与外部世界交互 |
```python
annotations=ToolAnnotations(
readOnlyHint=True, # 不修改外部状态
openWorldHint=True # 调用外部 API
)
```
资料来源：[servers/e2b/server.py](https://github.com/mcparmory/registry/blob/main/servers/e2b/server.py)
## 分发包配置
### PyPI 分发配置
```json
{
"registryType": "pypi",
"identifier": "mcparmory-",
"version": "1.0.0",
"runtimeHint": "uvx",
"transport": {
"type": "stdio"
}
}
```
### Docker/OCI 分发配置
```json
{
"registryType": "oci",
"identifier": "ghcr.io/mcparmory/:1.0.0",
"runtimeHint": "docker",
"transport": {
"type": "stdio"
}
}
```
资料来源：[servers/linkup/server.json](https://github.com/mcparmory/registry/blob/main/servers/linkup/server.json)
## 连接池配置
所有服务器统一使用 httpx 进行 HTTP 通信，并配置连接池参数：
```python
CONNECTION_POOL_SIZE = int(os.getenv("CONNECTION_POOL_SIZE", "100"))
MAX_KEEPALIVE_CONNECTIONS = int(os.getenv("MAX_KEEPALIVE_CONNECTIONS", "20"))
```
| 参数 | 说明 | 默认值 | 调整建议 |
|------|------|--------|----------|
| CONNECTION_POOL_SIZE | 最大连接池大小 | 100 | 高并发场景可增大 |
| MAX_KEEPALIVE_CONNECTIONS | 保活连接数 | 20 | 适当减少可节省资源 |
## 常见故障模式
### 1. 环境变量未加载
```python
# 症状：BASE_URL 使用默认值而非配置值
# 解决：确保 .env 文件存在于 server.py 同目录
try:
from dotenv import load_dotenv
_env_path = Path(__file__).parent / '.env'
if _env_path.exists():
load_dotenv(_env_path)
except ImportError:
pass # python-dotenv 未安装，环境变量需手动设置
```
### 2. 参数验证失败
```python
# 症状：抛出 ValueError，提示参数无效
# 解决：检查 Pydantic 模型的字段约束
try:
_request = _models.SomeRequest(...)
except pydantic.ValidationError as _validation_err:
logging.error(f"参数验证失败: {_validation_err}")
raise ValueError(f"无效参数: {_validation_err.errors()}")
```
### 3. 认证配置缺失
```python
# 症状：API 请求返回 401 Unauthorized
# 解决：确保环境变量中设置了正确的认证凭据
_auth = await _get_auth_for_operation("operation_name")
if not _auth:
raise ValueError(f"操作 {operation_name} 缺少认证配置")
```
### 4. 连接池耗尽
```python
# 症状：高并发时请求阻塞或超时
# 解决：增大 CONNECTION_POOL_SIZE 环境变量
# export CONNECTION_POOL_SIZE=200
```
## 最佳实践
1. **始终使用 .env 文件**：在服务器目录放置 .env 文件存储敏感配置
2. **参数验证**：所有工具参数使用 Pydantic Field 进行类型约束
3. **错误处理**：对 Pydantic 验证错误进行捕获和日志记录
4. **日志级别**：生产环境建议使用 WARNING 或 ERROR 级别
5. **超时配置**：根据 API 响应时间调整 HTTPX_TIMEOUT
## See Also
- [MCP 协议规范](https://modelcontextprotocol.io)
- [FastMCP 框架文档](https://github.com/jlowin/fastmcp)
- [Pydantic v2 文档](https://docs.pydantic.dev/)
---
## 认证机制详解
### 相关页面
相关主题：[服务器标准模式](#page-server-pattern), [配置参考](#page-configuration)
相关源码文件
以下源码文件用于生成本页说明：
- [servers/github/_auth.py](https://github.com/mcparmory/registry/blob/main/servers/github/_auth.py)
- [servers/canvas/_auth.py](https://github.com/mcparmory/registry/blob/main/servers/canvas/_auth.py)
- [servers/posthog/_auth.py](https://github.com/mcparmory/registry/blob/main/servers/posthog/_auth.py)
- [servers/launchdarkly/_auth.py](https://github.com/mcparmory/registry/blob/main/servers/launchdarkly/_auth.py)
- [servers/atlassian-confluence/server.py](https://github.com/mcparmory/registry/blob/main/servers/atlassian-confluence/server.py)
- [servers/google-search-console/server.py](https://github.com/mcparmory/registry/blob/main/servers/google-search-console/server.py)
# 认证机制详解
## 概述
MCP Registry 项目中的 MCP 服务器（Model Context Protocol Server）实现了统一的认证机制，用于在 AI 代理与外部服务之间建立安全连接。每个服务器都拥有独立的 `_auth.py` 认证模块，负责将具体的 API 操作映射到相应的认证方法。
这种设计遵循了**每个服务一个认证配置**的原则，使得认证逻辑与业务逻辑分离，便于维护和扩展。开发者可以根据不同服务的 API 安全要求，灵活配置所需的认证方式。
## 认证类型体系
MCP Registry 支持多种认证类型，以满足不同外部服务的安全要求。根据源码分析，当前系统支持以下认证方式：
| 认证类型 | 描述 | 适用场景 | 代表服务器 |
|---------|------|---------|-----------|
| OAuth2 | 标准 OAuth 2.0 授权流程 | 需要用户授权的 Web 服务 | Canvas |
| PersonalAPIKeyAuth | 个人 API 密钥认证 | 团队协作平台 | PostHog |
| ApiKey | API 密钥认证 | 开发者平台 | LaunchDarkly |
| PersonalAccessToken | 个人访问令牌 | 代码托管服务 | GitHub |
| bearerAuth | Bearer Token 认证 | RESTful API 服务 | Canvas |
资料来源：[servers/canvas/_auth.py](https://github.com/mcparmory/registry/blob/main/servers/canvas/_auth.py)
## 认证配置结构
### 认证映射机制
每个服务器的 `_auth.py` 文件导出一个字典结构，将操作名称映射到所需的认证类型列表。这种映射方式允许同一操作支持多种认证方式，提高了系统的兼容性。
```python
# 认证映射示例
OPERATION_AUTH = {
"operation_name": [["AuthType1"], ["AuthType2"]],
"list_pull_requests": [["OAuth2"], ["PersonalAccessToken"]],
}
```
在上述结构中，`operation_name` 对应的列表可以包含多个认证方案，每个方案作为一个独立的列表元素。当第一个认证方案不可用时，系统可以回退到下一个方案。
资料来源：[servers/github/_auth.py](https://github.com/mcparmory/registry/blob/main/servers/github/_auth.py)
### 认证数据结构
认证配置采用嵌套列表结构，支持多认证方案定义。每个操作的认证需求以列表形式存储，便于系统按顺序尝试不同的认证方法。
```mermaid
graph TD
A[API 操作请求] --> B{查找认证配置}
B --> C[获取认证方案列表]
C --> D[尝试第一个认证方案]
D --> E{认证成功?}
E -->|是| F[执行操作]
E -->|否| G[尝试下一个认证方案]
G --> H{还有更多方案?}
H -->|是| D
H -->|否| I[返回认证失败]
```
## 认证流程详解
### 请求级别的认证注入
认证信息的注入发生在 HTTP 请求层面。当执行工具请求时，系统会根据操作名称从 `_auth.py` 获取所需的认证类型，然后从配置或环境变量中提取相应的凭证。
```python
# 从源码中提取的认证注入流程
async def _execute_tool_request(
tool_name: str,
method: str,
path: str,
request_id: str,
headers: dict,
) -> tuple[dict[str, Any], int]:
# 获取操作对应的认证方案
_auth = await _get_auth_for_operation(tool_name)
```
资料来源：[servers/atlassian-confluence/server.py](https://github.com/mcparmory/registry/blob/main/servers/atlassian-confluence/server.py)
### 多认证方案回退机制
系统支持认证方案的回退机制。当主认证方案失效或不可用时，系统会自动尝试备选方案，确保请求能够成功执行。
```mermaid
sequenceDiagram
participant C as 客户端
participant S as MCP服务器
participant A1 as 主认证服务
participant A2 as 备选认证服务
C->>S: 发送请求
S->>S: 获取认证配置
S->>A1: 使用OAuth2尝试认证
A1-->>S: 认证失败/不可用
S->>A2: 使用PersonalAccessToken重试
A2-->>S: 认证成功
S->>C: 返回结果
```
## 各服务认证实现
### GitHub 服务认证
GitHub 服务器支持 OAuth2 和 PersonalAccessToken 两种认证方式，适用于代码仓库管理、Issue 追踪、PR 操作等场景。
| 操作类型 | 认证方式 | 说明 |
|---------|---------|------|
| list_pull_requests | OAuth2, PersonalAccessToken | 列表拉取请求 |
| create_pull_request | OAuth2, PersonalAccessToken | 创建拉取请求 |
| get_pages_site | OAuth2, PersonalAccessToken | 获取 Pages 站点 |
| list_repository_custom_properties | OAuth2, PersonalAccessToken | 列出自定义属性 |
资料来源：[servers/github/_auth.py](https://github.com/mcparmory/registry/blob/main/servers/github/_auth.py)
### Canvas LMS 服务认证
Canvas 学习管理系统采用 OAuth2 和 Bearer Token 双重认证机制，确保教育平台数据访问的安全性。
```python
# Canvas 认证配置片段
OPERATION_AUTH = {
"list_pinned_discussion_topics": [["OAuth2"], ["bearerAuth"]],
"get_discussion_topic": [["OAuth2"], ["bearerAuth"]],
"update_discussion_topic": [["OAuth2"], ["bearerAuth"]],
"list_discussion_entries": [["OAuth2"], ["bearerAuth"]],
}
```
Canvas 的认证设计特别关注教育数据的隐私性，支持细粒度的权限控制，适用于课程管理、作业批改、成绩录入等教学场景。
资料来源：[servers/canvas/_auth.py](https://github.com/mcparmory/registry/blob/main/servers/canvas/_auth.py)
### PostHog 分析平台认证
PostHog 使用 PersonalAPIKeyAuth 进行认证，适用于产品分析、用户行为追踪、A/B 测试等数据驱动场景。
| 功能模块 | 认证方式 | 操作示例 |
|---------|---------|---------|
| 洞察管理 | PersonalAPIKeyAuth | get_insight, update_insight |
| 实验管理 | PersonalAPIKeyAuth | create_experiment, launch_experiment |
| 数据导出 | PersonalAPIKeyAuth | list_exports, create_export |
| 注释功能 | PersonalAPIKeyAuth | list_annotations, create_annotation |
PostHog 的认证覆盖了从基础分析到高级实验的全部操作，确保产品数据分析的安全访问。
资料来源：[servers/posthog/_auth.py](https://github.com/mcparmory/registry/blob/main/servers/posthog/_auth.py)
### LaunchDarkly 服务认证
LaunchDarkly 采用简洁的 ApiKey 认证方式，适用于特性开关管理、环境配置、发布策略等 DevOps 场景。
```python
# LaunchDarkly 认证操作映射
OPERATION_AUTH = {
"list_feature_flags": [["ApiKey"]],
"create_feature_flag": [["ApiKey"]],
"update_feature_flag": [["ApiKey"]],
"delete_feature_flag": [["ApiKey"]],
"list_release_policies": [["ApiKey"]],
}
```
资料来源：[servers/launchdarkly/_auth.py](https://github.com/mcparmory/registry/blob/main/servers/launchdarkly/_auth.py)
## 环境变量配置
### 认证凭证存储
MCP 服务器通过环境变量存储敏感凭证信息，支持 `.env` 文件配置。每个服务器定义其所需的环境变量，遵循统一的安全最佳实践。
```python
# 环境变量加载示例
try:
from dotenv import load_dotenv
_env_path = Path(__file__).parent / '.env'
if _env_path.exists():
load_dotenv(_env_path)
except ImportError:
pass
```
这种设计允许在不修改代码的情况下配置认证凭证，同时支持不同部署环境的配置隔离。
资料来源：[servers/google-search-console/server.py](https://github.com/mcparmory/registry/blob/main/servers/google-search-console/server.py)
### 常用环境变量
| 变量名 | 描述 | 示例值 |
|-------|------|--------|
| BASE_URL | API 基础地址 | https://api.example.com |
| PERSONAL_API_KEY | 个人 API 密钥 | pk_xxxxxxxxxxxx |
| OAUTH_CLIENT_ID | OAuth 客户端 ID | client_id_value |
| OAUTH_CLIENT_SECRET | OAuth 客户端密钥 | client_secret_value |
| LOG_LEVEL | 日志级别 | DEBUG, INFO, WARNING, ERROR |
## 认证安全最佳实践
### 凭证管理建议
1. **敏感信息隔离**：所有认证凭证应存储在环境变量或安全的密钥管理系统中，避免硬编码到源码
2. **最小权限原则**：为不同操作分配适当的认证方式，确保只授予必要的访问权限
3. **凭证轮换**：定期更换 API 密钥和个人访问令牌，减少凭证泄露风险
4. **日志脱敏**：在日志输出时对敏感凭证进行脱敏处理，防止信息泄露
### 多认证方案的设计优势
MCP Registry 采用的多认证方案回退机制具有以下优势：
- **兼容性**：支持同一服务在不同时期采用不同认证方式
- **容错性**：主认证方案失败时可自动切换到备选方案
- **灵活性**：便于新增认证方式而不影响现有功能
- **可维护性**：认证逻辑集中管理，便于统一升级和修复
## 故障排查指南
### 常见认证错误
| 错误类型 | 表现症状 | 解决方案 |
|---------|---------|---------|
| 凭证缺失 | KeyError 或 undefined variable | 检查环境变量配置 |
| 权限不足 | 403 Forbidden | 确认账户拥有相应操作权限 |
| Token 过期 | 401 Unauthorized | 刷新或重新获取认证令牌 |
| 认证方案不支持 | Authentication scheme not supported | 检查服务器支持的认证类型 |
### 调试方法
1. **启用详细日志**：设置 `LOG_LEVEL=DEBUG` 查看完整的认证流程
2. **验证凭证有效性**：直接调用 API 确认凭证状态
3. **检查认证配置**：确认 `_auth.py` 中的操作映射是否正确
4. **环境隔离测试**：在干净环境中重新配置认证信息
## 架构总结
MCP Registry 的认证机制采用**声明式配置 + 运行时注入**的设计模式，将认证逻辑与业务逻辑完全解耦。这种设计使得：
- 每个服务可以独立定义其认证策略
- 新增认证类型时无需修改核心框架
- 认证方案的切换和扩展极为便捷
- 单元测试可以轻松模拟不同的认证场景
通过统一的认证抽象层，MCP Registry 能够安全地连接多种外部服务，为 AI 代理提供稳定可靠的数据访问能力。
---
## 延伸阅读
- [服务器配置指南](./服务器配置指南.md)
- [工具使用手册](./工具使用手册.md)
- [MCP 协议规范](./MCP协议规范.md)
---
## 部署指南
### 相关页面
相关主题：[配置参考](#page-configuration), [故障排除](#page-troubleshooting)
相关源码文件
以下源码文件用于生成本页说明：
- [README.md](https://github.com/mcparmory/registry/blob/main/README.md)
- [servers/perplexity/server.json](https://github.com/mcparmory/registry/blob/main/servers/perplexity/server.json)
- [servers/perplexity/server.py](https://github.com/mcparmory/registry/blob/main/servers/perplexity/server.py)
- [servers/linkup/server.json](https://github.com/mcparmory/registry/blob/main/servers/linkup/server.json)
- [servers/e2b/server.json](https://github.com/mcparmory/registry/blob/main/servers/e2b/server.json)
- [servers/pagerduty/server.json](https://github.com/mcparmory/registry/blob/main/servers/pagerduty/server.json)
- [servers/atlassian-confluence/server.py](https://github.com/mcparmory/registry/blob/main/servers/atlassian-confluence/server.py)
- [servers/google-search-console/server.py](https://github.com/mcparmory/registry/blob/main/servers/google-search-console/server.py)
- [servers/parallel/server.json](https://github.com/mcparmory/registry/blob/main/servers/parallel/server.json)
# 部署指南
本指南介绍如何在各种环境中部署和配置 MCP（Model Context Protocol）服务器。MCP Registry 提供了一系列独立的 Python 包，每个服务器对应一个特定的服务集成，可通过多种方式部署运行。
## 概述
MCP Registry 的核心设计理念是**每个服务器都是独立的 PyPI 包**，遵循 Model Context Protocol 标准。服务器支持三种部署方式：
| 部署方式 | 说明 | 适用场景 |
|---------|------|---------|
| **uvx** | 无需安装，直接运行 | 快速测试、开发环境 |
| **pip** | 安装到本地 Python 环境 | 生产环境、长期运行 |
| **Docker** | 容器化部署 | 微服务架构、隔离环境 |
资料来源：[README.md](https://github.com/mcparmory/registry/blob/main/README.md)
### 支持的 MCP 客户端
部署完成的服务器可与以下客户端集成：
- Claude Desktop
- Cursor
- Codex
- Claude Code
## 环境准备
### 系统要求
| 要求 | 最低版本 | 推荐版本 |
|-----|---------|---------|
| Python | 3.10+ | 3.11+ |
| pip | 21.0+ | 最新版 |
| Docker | 20.10+ | 24.0+ |
| uv | 0.1.0+ | 最新版 |
### 安装 uvx（推荐用于快速启动）
uvx 是 uv 工具的即时执行模式，无需预先安装包即可运行：
```bash
# 使用 pip 安装 uv
pip install uv
# 或使用 curl 安装
curl -LsSf https://astral.sh/uv/install.sh | sh
```
## 部署方式
### 方式一：uvx 快速运行
uvx 模式适合快速测试和临时使用，服务器会自动下载并执行：
```bash
# 运行 GitHub 服务器
uvx mcparmory-github
# 运行 Perplexity 服务器
uvx mcparmory-perplexity
# 运行 Slack 服务器
uvx mcparmory-slack
```
资料来源：[README.md](https://github.com/mcparmory/registry/blob/main/README.md)
### 方式二：pip 安装
对于生产环境，建议使用 pip 将服务器安装到本地环境：
```bash
# 安装单个服务器
pip install mcparmory-github
pip install mcparmory-perplexity
pip install mcparmory-slack
# 安装后运行
mcparmory-github
mcparmory-perplexity
```
### 方式三：Docker 容器部署
每个服务器都提供了预构建的 Docker 镜像，支持 OCI 标准：
```mermaid
graph TD
A[启动容器] --> B{镜像来源}
B --> C[使用预构建镜像]
B --> D[本地构建镜像]
C --> E[配置环境变量]
D --> E
E --> F[连接到 MCP 客户端]
```
#### 预构建镜像使用
服务器配置中定义了标准化的 OCI 镜像：
```json
{
"registryType": "oci",
"identifier": "ghcr.io/mcparmory/perplexity:1.0.2",
"runtimeHint": "docker",
"transport": {
"type": "stdio"
}
}
```
资料来源：[servers/perplexity/server.json](https://github.com/mcparmory/registry/blob/main/servers/perplexity/server.json)
#### 常用服务器镜像对照表
| 服务器 | Docker 镜像 | PyPI 包 |
|-------|-------------|---------|
| perplexity | `ghcr.io/mcparmory/perplexity:1.0.2` | `mcparmory-perplexity` |
| e2b | `ghcr.io/mcparmory/e2b:1.0.5` | `mcparmory-e2b` |
| linkup | `ghcr.io/mcparmory/linkup:1.0.2` | `mcparmory-linkup` |
| parallel | `ghcr.io/mcparmory/parallel:1.0.2` | `mcparmory-parallel` |
| pagerduty | `ghcr.io/mcparmory/pagerduty:1.0.2` | `mcparmory-pagerduty` |
资料来源：[servers/e2b/server.json](https://github.com/mcparmory/registry/blob/main/servers/e2b/server.json)、[servers/pagerduty/server.json](https://github.com/mcparmory/registry/blob/main/servers/pagerduty/server.json)
## MCP 客户端配置
### Claude Desktop 配置
在 `claude_desktop_config.json` 中添加服务器配置：
```json
{
"mcpServers": {
"github": {
"command": "uvx",
"args": ["mcparmory-github"],
"env": {
"BEARER_TOKEN": "ghp_your_token_here"
}
},
"perplexity": {
"command": "uvx",
"args": ["mcparmory-perplexity"],
"env": {
"PERPLEXITY_API_KEY": "your_api_key_here"
}
}
}
}
```
资料来源：[README.md](https://github.com/mcparmory/registry/blob/main/README.md)
### 通用 MCP 客户端配置模板
```json
{
"mcpServers": {
"": {
"command": "uvx",
"args": ["mcparmory-"],
"env": {
"": ""
}
}
}
}
```
## 环境变量配置
### 服务器通用配置
每个服务器支持以下通用环境变量：
| 环境变量 | 默认值 | 说明 |
|---------|-------|------|
| `BASE_URL` | 服务默认值 | API 基础 URL |
| `CONNECTION_POOL_SIZE` | 100 | HTTP 连接池大小 |
| `MAX_KEEPALIVE_CONNECTIONS` | 20 | 最大 Keep-Alive 连接数 |
| `LOG_LEVEL` | INFO | 日志级别 (DEBUG/INFO/WARNING/ERROR) |
资料来源：[servers/perplexity/server.py](https://github.com/mcparmory/registry/blob/main/servers/perplexity/server.py)
### .env 文件配置
服务器支持通过 `.env` 文件加载环境变量：
```python
try:
from dotenv import load_dotenv
_env_path = Path(__file__).parent / '.env'
if _env_path.exists():
load_dotenv(_env_path)
except ImportError:
pass
```
资料来源：[servers/atlassian-confluence/server.py](https://github.com/mcparmory/registry/blob/main/servers/atlassian-confluence/server.py)
创建 `.env` 文件示例：
```bash
# Perplexity 服务器配置
PERPLEXITY_API_KEY=pplx-your-api-key-here
LOG_LEVEL=DEBUG
# Confluence 服务器配置
CONFLUENCE_API_TOKEN=your-api-token
CONFLUENCE_USER_EMAIL=your-email@example.com
BASE_URL=https://your-domain.atlassian.net/wiki
```
### 认证配置
不同服务器支持多种认证方式：
| 认证类型 | 说明 | 适用服务器 |
|---------|------|-----------|
| API Key | 直接的 API 密钥认证 | PagerDuty, Perigon |
| Bearer Token | OAuth 或 Personal Access Token | GitHub |
| Basic Auth | 用户名/密码组合 | 部分服务 |
| OAuth2 | 完整的 OAuth 流程 | Confluence |
| JWT | JSON Web Token | 部分企业服务 |
服务器根据 OpenAPI 规范自动处理认证头的注入：
```python
# 认证头由 _auth.py 模块统一管理
_auth = await _get_auth_for_operation("")
```
资料来源：[servers/launchdarkly/_auth.py](https://github.com/mcparmory/registry/blob/main/servers/launchdarkly/_auth.py)
## 部署架构
### 单服务器部署
适用于单一服务集成的简单场景：
```mermaid
graph LR
A[MCP 客户端] -->|stdio| B[单个 MCP 服务器]
B --> C[目标 API]
```
### 多服务器部署
生产环境通常需要同时运行多个服务器：
```mermaid
graph TD
A[MCP 客户端] --> B[GitHub 服务器]
A --> C[Slack 服务器]
A --> D[Confluence 服务器]
B --> E[GitHub API]
C --> F[Slack API]
D --> G[Confluence API]
```
### Docker Compose 编排
推荐使用 Docker Compose 管理多服务器部署：
```yaml
version: '3.8'
services:
perplexity:
image: ghcr.io/mcparmory/perplexity:1.0.2
environment:
- PERPLEXITY_API_KEY=${PERPLEXITY_API_KEY}
transport: stdio
pagerduty:
image: ghcr.io/mcparmory/pagerduty:1.0.2
environment:
- PAGERDUTY_API_KEY=${PAGERDUTY_API_KEY}
transport: stdio
```
## 传输协议
### stdio 传输（默认）
所有服务器默认使用 stdio 传输协议：
```json
{
"transport": {
"type": "stdio"
}
}
```
stdio 模式通过标准输入/输出流与客户端通信，适合本地和容器环境：
```python
# 服务器启动时自动初始化 stdio 传输
from fastmcp import FastMCP
mcp = FastMCP(SERVER_NAME)
mcp.run(transport="stdio")
```
资料来源：[servers/google-search-console/server.py](https://github.com/mcparmory/registry/blob/main/servers/google-search-console/server.py)
### HTTP/SSE 传输（可选）
部分服务器支持 HTTP 服务器发送事件（SSE）传输，适用于 Web 集成场景。
## 故障排除
### 常见部署问题
| 问题 | 可能原因 | 解决方案 |
|-----|---------|---------|
| 找不到命令 `mcparmory-xxx` | 包未正确安装 | 重新执行 `pip install mcparmory-xxx` |
| 认证失败 | 环境变量未设置 | 检查 `.env` 文件或客户端配置 |
| 连接超时 | 网络问题或 BASE_URL 错误 | 验证网络和 BASE_URL 配置 |
| 权限不足 | API Token 权限不够 | 在目标服务中更新 Token 权限范围 |
### 日志调试
启用 DEBUG 级别日志获取详细调试信息：
```bash
# 通过环境变量启用
export LOG_LEVEL=DEBUG
uvx mcparmory-github
```
或在 Docker 中：
```bash
docker run -e LOG_LEVEL=DEBUG ghcr.io/mcparmory/github:latest
```
### 连接池调优
对于高并发场景，调整连接池参数：
```bash
export CONNECTION_POOL_SIZE=200
export MAX_KEEPALIVE_CONNECTIONS=50
uvx mcparmory-perplexity
```
## 安全最佳实践
1. **环境变量管理**
- 敏感信息存储在 `.env` 文件中
- `.env` 文件添加到 `.gitignore`
- 使用密钥管理服务（如 AWS Secrets Manager）进行生产环境配置
2. **网络隔离**
- 使用 Docker 网络隔离 MCP 服务器
- 配置防火墙规则限制 API 访问
3. **最小权限原则**
- 为 API Token 设置最小必要权限
- 定期轮换密钥
4. **容器安全**
- 使用非 root 用户运行容器
- 定期更新基础镜像
## 升级与维护
### 版本更新
```bash
# uvx 模式 - 重新运行即使用最新版本
uvx mcparmory-github
# pip 模式 - 升级到最新版本
pip install --upgrade mcparmory-github
# Docker 模式 - 拉取最新镜像
docker pull ghcr.io/mcparmory/github:latest
```
### 查看当前版本
```bash
# 服务器启动时会输出版本信息
uvx mcparmory-github --version
```
## 相关资源
- [快速开始指南](README.md)
- [服务器列表](../servers)
- [认证配置参考](../authentication)
- [API 参考文档](../api-reference)
## 参见
- [项目主页](https://github.com/mcparmory/registry)
- [MCP 协议规范](https://modelcontextprotocol.io)
- [FastMCP 框架文档](https://github.com/jlowin/fastmcp)
---
## 配置参考
### 相关页面
相关主题：[部署指南](#page-deployment), [认证机制详解](#page-authentication)
相关源码文件
以下源码文件用于生成本页说明：
- [servers/perplexity/server.json](https://github.com/mcparmory/registry/blob/main/servers/perplexity/server.json)
- [servers/perplexity/server.py](https://github.com/mcparmory/registry/blob/main/servers/perplexity/server.py)
- [servers/google-search-console/server.py](https://github.com/mcparmory/registry/blob/main/servers/google-search-console/server.py)
- [servers/atlassian-confluence/server.py](https://github.com/mcparmory/registry/blob/main/servers/atlassian-confluence/server.py)
- [servers/atlassian-confluence/_models.py](https://github.com/mcparmory/registry/blob/main/servers/atlassian-confluence/_models.py)
- [servers/e2b/server.json](https://github.com/mcparmory/registry/blob/main/servers/e2b/server.json)
- [servers/linkup/server.json](https://github.com/mcparmory/registry/blob/main/servers/linkup/server.json)
- [servers/pagerduty/server.json](https://github.com/mcparmory/registry/blob/main/servers/pagerduty/server.json)
- [servers/posthog/_auth.py](https://github.com/mcparmory/registry/blob/main/servers/posthog/_auth.py)
- [servers/launchdarkly/_auth.py](https://github.com/mcparmory/registry/blob/main/servers/launchdarkly/_auth.py)
- [servers/canvas/_auth.py](https://github.com/mcparmory/registry/blob/main/servers/canvas/_auth.py)
# 配置参考
本文档详细介绍 MCP Registry 仓库中各服务器组件的配置方式、环境变量规范以及认证机制。所有服务器均基于 [FastMCP](https://github.com/jlowin/fastmcp) 框架构建，遵循统一的配置模式。
---
## 概述
MCP Registry 是一个模型上下文协议（Model Context Protocol）服务器集合，为 AI 代理提供各种工具和服务。每个服务器都是独立的 Python 包，支持通过 `uvx` 或 `docker` 两种运行时方式部署。
配置系统包含以下几个核心层面：
| 配置层级 | 说明 | 文件位置 |
|---------|------|---------|
| 服务器元数据 | 服务器名称、版本、描述 | `server.json` |
| 运行时参数 | 环境变量、连接池、超时设置 | `server.py` |
| 认证配置 | API 密钥、OAuth2 认证 | `_auth.py` |
| 请求模型 | API 参数验证和数据模型 | `_models.py` |
---
## 服务器元数据配置
### server.json 结构
每个服务器目录下都包含一个 `server.json` 文件，定义了服务器的元数据和包信息：
```json
{
"$schema": "https://static.modelcontextprotocol.io/schemas/2025-12-11/server.schema.json",
"name": "com.mcparmory/perplexity",
"description": "Search the web, generate AI responses, and create embeddings with real-time information",
"version": "1.0.2",
"repository": {
"url": "https://github.com/mcparmory/registry",
"source": "github"
},
"packages": [
{
"registryType": "pypi",
"identifier": "mcparmory-perplexity",
"version": "1.0.2",
"runtimeHint": "uvx",
"transport": {
"type": "stdio"
}
}
]
}
```
资料来源：[servers/perplexity/server.json](https://github.com/mcparmory/registry/blob/main/servers/perplexity/server.json)
### server.json 字段说明
| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `$schema` | string | 是 | JSON Schema 验证 URI |
| `name` | string | 是 | 服务器唯一标识符，格式为 `com.mcparmory/{service}` |
| `description` | string | 是 | 服务器功能描述 |
| `version` | string | 是 | 语义化版本号 (如 `1.0.2`) |
| `repository.url` | string | 是 | GitHub 仓库地址 |
| `repository.source` | string | 是 | 固定值 `github` |
| `packages` | array | 是 | 可用包列表 |
| `packages[].registryType` | string | 是 | 包类型：`pypi` 或 `oci` |
| `packages[].identifier` | string | 是 | 包标识符 |
| `packages[].runtimeHint` | string | 是 | 运行时提示：`uvx` 或 `docker` |
| `packages[].transport.type` | string | 是 | 传输类型：固定值 `stdio` |
---
## 运行时配置
### 环境变量配置
服务器通过 `server.py` 文件加载环境变量进行配置。以下是常见的配置项：
资料来源：[servers/google-search-console/server.py:41-45](https://github.com/mcparmory/registry/blob/main/servers/google-search-console/server.py)
```python
BASE_URL = os.getenv("BASE_URL", "https://searchconsole.googleapis.com")
SERVER_NAME = "Google Search Console"
SERVER_VERSION = "1.0.3"
CONNECTION_POOL_SIZE = int(os.getenv("CONNECTION_POOL_SIZE", "100"))
MAX_KEEPALIVE_CONNECTIONS = int(os.getenv("MAX_KEEPALIVE_CONNECTIONS", "20"))
```
### 通用环境变量
| 环境变量 | 类型 | 默认值 | 说明 |
|---------|------|--------|------|
| `BASE_URL` | string | 服务商 API 默认地址 | API 请求基础 URL |
| `SERVER_NAME` | string | 服务器名称 | 服务器显示名称 |
| `SERVER_VERSION` | string | 版本号 | 服务器版本 |
| `CONNECTION_POOL_SIZE` | int | 100 | HTTP 连接池大小 |
| `MAX_KEEPALIVE_CONNECTIONS` | int | 20 | 最大保活连接数 |
| `LOG_LEVEL` | string | INFO | 日志级别：DEBUG, INFO, WARNING, ERROR |
| `HTTPX_TIMEOUT` | int | 60 | HTTP 请求超时时间（秒） |
资料来源：[servers/google-search-console/server.py:47](https://github.com/mcparmory/registry/blob/main/servers/google-search-console/server.py)
### 日志配置
日志级别通过 `LOG_LEVEL` 环境变量控制，支持以下级别：
```python
LOG_LEVEL = os.getenv("LOG_LEVEL", "INFO").upper()
if LOG_LEVEL not in ("DEBUG", "INFO", "WARNING", "ERROR"):
LOG_LEVEL = "INFO"
```
资料来源：[servers/google-search-console/server.py:48-51](https://github.com/mcparmory/registry/blob/main/servers/google-search-console/server.py)
### .env 文件加载
服务器支持通过 `.env` 文件加载环境变量，文件位于服务器目录：
```python
try:
from dotenv import load_dotenv
_env_path = Path(__file__).parent / '.env'
if _env_path.exists():
load_dotenv(_env_path)
except ImportError:
pass
```
资料来源：[servers/perplexity/server.py:28-33](https://github.com/mcparmory/registry/blob/main/servers/perplexity/server.py)
---
## 认证机制
### 认证类型概览
MCP Registry 支持多种认证机制，通过 `_auth.py` 文件定义每个操作的认证要求：
| 认证类型 | 说明 | 使用场景 |
|---------|------|---------|
| `PersonalAPIKeyAuth` | 个人 API 密钥认证 | PostHog, Perplexity |
| `ApiKey` | 标准 API 密钥 | LaunchDarkly, PagerDuty |
| `OAuth2` | OAuth 2.0 授权 | Canvas LMS |
| `bearerAuth` | Bearer Token 认证 | 部分 API 集成 |
资料来源：[servers/posthog/_auth.py](https://github.com/mcparmory/registry/blob/main/servers/posthog/_auth.py)
### 个人 API 密钥认证
PostHog 等服务使用个人 API 密钥进行认证：
```python
"get_insight": [["PersonalAPIKeyAuth"]],
"update_insight": [["PersonalAPIKeyAuth"]],
"create_experiment": [["PersonalAPIKeyAuth"]],
```
资料来源：[servers/posthog/_auth.py:1-5](https://github.com/mcparmory/registry/blob/main/servers/posthog/_auth.py)
### OAuth2 认证
Canvas LMS 使用 OAuth2 和 Bearer Token 认证：
```python
"list_discussion_topics": [["OAuth2"], ["bearerAuth"]],
"get_discussion_topic": [["OAuth2"], ["bearerAuth"]],
"create_discussion_entry": [["OAuth2"], ["bearerAuth"]],
```
资料来源：[servers/canvas/_auth.py](https://github.com/mcparmory/registry/blob/main/servers/canvas/_auth.py)
### API 密钥认证
LaunchDarkly 和 PagerDuty 使用标准 API 密钥认证：
```python
"create_agent_graph": [["ApiKey"]],
"get_agent_graph": [["ApiKey"]],
"update_agent_graph": [["ApiKey"]],
```
资料来源：[servers/launchdarkly/_auth.py](https://github.com/mcparmory/registry/blob/main/servers/launchdarkly/_auth.py)
---
## 数据模型配置
### Pydantic 模型结构
每个服务器包含 `_models.py` 文件，定义了请求和响应的数据模型。模型分为严格模式（StrictModel）和宽松模式（PermissiveModel）：
```python
from _validators import StrictModel
from pydantic import Field
class CreateConnectionRequestBody(StrictModel):
"""创建新连接的请求体"""
name: str = Field(..., description="连接的友好名称")
metadata: dict[str, Any] | None = Field(
default=None,
description="自定义元数据键值对"
)
```
资料来源：[servers/ragie/_models.py](https://github.com/mcparmory/registry/blob/main/servers/ragie/_models.py)
### 模型字段类型
| 字段类型 | 说明 | 示例 |
|---------|------|------|
| `str` | 字符串 | `Field(..., description="描述")` |
| `int` | 整数 | `Field(default=10, ge=1, le=100)` |
| `float` | 浮点数 | `latitude: float | None` |
| `bool` | 布尔值 | `show_full_text: bool | None` |
| `list[str]` | 字符串列表 | `contact_ids: list[str]` |
| `dict[str, Any]` | 字典 | `metadata: dict[str, Any]` |
| `Literal[...]` | 字面量枚举 | `type_: Literal["call", "email"]` |
### 字段验证约束
Pydantic 模型支持丰富的验证约束：
```python
class ListConnectionsConnectionsGetRequestQuery(StrictModel):
page_size: int | None = Field(
default=None,
description="每页返回数量",
ge=1, # 最小值
le=100 # 最大值
)
filter_: str | None = Field(
default=None,
validation_alias="filter",
serialization_alias="filter"
)
```
资料来源：[servers/ragie/_models.py](https://github.com/mcparmory/registry/blob/main/servers/ragie/_models.py)
---
## 工具函数配置
### 工具定义
服务器通过 FastMCP 装饰器定义可用的工具函数：
```python
@mcp.tool(
title="List Page Watches",
annotations=ToolAnnotations(
readOnlyHint=True,
openWorldHint=True
),
)
async def list_page_watches(
id_: str = Field(..., alias="id", description="页面唯一标识符"),
limit: str | None = Field(None, description="返回记录的最大数量")
) -> dict[str, Any] | ToolResult:
"""获取指定页面的所有监视记录"""
```
资料来源：[servers/atlassian-confluence/server.py](https://github.com/mcparmory/registry/blob/main/servers/atlassian-confluence/server.py)
### 工具注解说明
| 注解 | 说明 |
|------|------|
| `readOnlyHint` | 表示该操作是否只读 |
| `openWorldHint` | 表示是否访问外部系统 |
### 请求验证
工具函数使用 Pydantic 进行参数验证：
```python
try:
_request = _models.GetWatchesForPageRequest(
path=_models.GetWatchesForPageRequestPath(id_=id_),
query=_models.GetWatchesForPageRequestQuery(limit=_limit)
)
except pydantic.ValidationError as _validation_err:
logging.error(f"参数验证失败: {_validation_err}")
raise ValueError(f"无效参数: {_validation_err.errors()}") from _validation_err
```
资料来源：[servers/atlassian-confluence/server.py](https://github.com/mcparmory/registry/blob/main/servers/atlassian-confluence/server.py)
---
## 服务器配置示例
### Perplexity 服务器
```json
{
"name": "com.mcparmory/perplexity",
"version": "1.0.2",
"BASE_URL": "https://api.perplexity.ai",
"transport": "stdio"
}
```
### E2B 安全沙箱服务器
```json
{
"name": "com.mcparmory/e2b",
"version": "1.0.5",
"description": "Create and manage secure sandboxes for running AI agent code"
}
```
资料来源：[servers/e2b/server.json](https://github.com/mcparmory/registry/blob/main/servers/e2b/server.json)
### PagerDuty 事件管理服务器
```json
{
"name": "com.mcparmory/pagerduty",
"version": "1.0.2",
"description": "Manage incidents, on-call schedules, escalation policies, and alert notifications"
}
```
资料来源：[servers/pagerduty/server.json](https://github.com/mcparmory/registry/blob/main/servers/pagerduty/server.json)
---
## 配置架构图
```mermaid
graph TD
A[用户配置] --> B[.env 文件]
A --> C[环境变量]
B --> D[server.py 加载]
C --> D
D --> E{运行时模式}
E -->|开发| F[调试日志]
E -->|生产| G[INFO 日志]
F --> H[HTTPX 客户端]
G --> H
H --> I[API 请求]
I --> J{认证检查}
J -->|通过| K[执行业务逻辑]
J -->|失败| L[返回错误]
K --> M[返回 ToolResult]
```
---
## 常见配置问题
### 问题 1：环境变量未生效
**症状**：配置的环境变量没有生效，使用默认值。
**解决方案**：
1. 确保 `.env` 文件位于服务器目录
2. 检查环境变量名称是否正确（区分大小写）
3. 验证 `python-dotenv` 包已安装
### 问题 2：认证失败
**症状**：API 请求返回 401 或 403 错误。
**解决方案**：
1. 检查 API 密钥是否正确设置
2. 确认认证类型与 API 服务商要求一致
3. 验证密钥是否具有所需的操作权限
### 问题 3：连接池耗尽
**症状**：高并发时出现连接超时错误。
**解决方案**：
```bash
export CONNECTION_POOL_SIZE=200
export MAX_KEEPALIVE_CONNECTIONS=50
```
### 问题 4：请求超时
**症状**：长时间运行的请求被中断。
**解决方案**：
```python
HTTPX_TIMEOUT = httpx.Timeout(
connect=30.0,
read=120.0,
write=30.0,
pool=30.0
)
```
---
## 最佳实践
1. **环境隔离**：开发、测试、生产环境使用不同的 `.env` 文件
2. **密钥安全**：敏感信息不要提交到版本控制系统，使用环境变量或密钥管理服务
3. **连接池调优**：根据预期负载调整 `CONNECTION_POOL_SIZE`
4. **日志级别**：生产环境建议使用 `INFO` 级别，避免过多调试输出
5. **超时设置**：为长时间运行的请求配置适当的超时时间
---
## 相关文档
- [MCP 服务器概览](../servers/overview)
- [认证机制详解](../authentication)
- [部署指南](../deployment)
- [故障排除](../troubleshooting)
---
## 参考链接
- [FastMCP 官方文档](https://github.com/jlowin/fastmcp)
- [Model Context Protocol 规范](https://modelcontextprotocol.io)
- [Pydantic 数据验证](https://docs.pydantic.dev)
---
## 故障排除
### 相关页面
相关主题：[部署指南](#page-deployment), [配置参考](#page-configuration)
相关源码文件
以下源码文件用于生成本页说明：
- [servers/github/server.py](https://github.com/mcparmory/registry/blob/main/servers/github/server.py)
- [servers/github/_auth.py](https://github.com/mcparmory/registry/blob/main/servers/github/_auth.py)
- [servers/github/_validators.py](https://github.com/mcparmory/registry/blob/main/servers/github/_validators.py)
- [servers/atlassian-confluence/server.py](https://github.com/mcparmory/registry/blob/main/servers/atlassian-confluence/server.py)
- [servers/perplexity/server.py](https://github.com/mcparmory/registry/blob/main/servers/perplexity/server.py)
- [servers/google-search-console/server.py](https://github.com/mcparmory/registry/blob/main/servers/google-search-console/server.py)
- [servers/e2b/server.json](https://github.com/mcparmory/registry/blob/main/servers/e2b/server.json)
- [servers/firecrawl/server.py](https://github.com/mcparmory/registry/blob/main/servers/firecrawl/server.py)
# 故障排除
本文档提供 mcparmory/registry MCP 服务器集合的常见故障排除指南。该项目包含多个预配置的 MCP 服务器实现，用于连接各种外部服务（如 GitHub、Confluence、Perplexity 等）。
## 常见问题概览
```mermaid
graph TD
A[MCP 服务器故障] --> B[认证问题]
A --> C[连接问题]
A --> D[参数验证错误]
A --> E[环境配置问题]
A --> F[运行时异常]
B --> B1[API 密钥缺失]
B --> B2[认证类型不匹配]
B --> B3[令牌过期]
C --> C1[网络超时]
C --> C2[连接池耗尽]
C --> C3[无效的 BASE_URL]
D --> D1[Pydantic 验证失败]
D --> D2[必填字段缺失]
E --> E1[.env 文件缺失]
E --> E2[环境变量未设置]
F --> F1[导入错误]
F --> F2[依赖缺失]
```
## 认证问题
### API 密钥缺失或无效
大多数 MCP 服务器需要通过环境变量设置 API 密钥。当缺少必要的认证凭证时，服务器会抛出认证错误。
**检查方法：**
各服务器的身份验证配置定义在 `_auth.py` 文件中。以 Posthog 服务器为例：
```python
资料来源：[servers/posthog/_auth.py:1-50](https://github.com/mcparmory/registry/blob/main/servers/posthog/_auth.py)
```
**常见环境变量：**
| 服务器 | 环境变量 | 说明 |
|--------|----------|------|
| Perplexity | `PERPLEXITY_API_KEY` | Perplexity API 访问密钥 |
| Google Search Console | `GOOGLE_API_KEY` | Google API 密钥 |
| PagerDuty | `PAGERDUTY_API_KEY` | PagerDuty API 令牌 |
| LaunchDarkly | `LAUNCHDARKLY_API_KEY` | LaunchDarkly API 密钥 |
### 认证类型不匹配
不同的外部 API 支持不同的认证方式。服务器实现会为每个操作指定所需的认证类型。
**认证类型配置示例：**
```python
资料来源：[servers/canvas/_auth.py:1-30](https://github.com/mcparmory/registry/blob/main/servers/canvas/_auth.py)
```
| 认证类型 | 说明 | 适用场景 |
|----------|------|----------|
| `PersonalAPIKeyAuth` | 个人 API 密钥认证 | Posthog、Perplexity |
| `ApiKey` | 标准 API 密钥 | PagerDuty、LaunchDarkly |
| `OAuth2` | OAuth 2.0 授权 | Canvas LMS |
| `bearerAuth` | Bearer 令牌认证 | 部分 Canvas 端点 |
**解决方案：**
1. 确认外部服务使用的认证类型
2. 检查环境变量配置是否正确
3. 验证 API 密钥是否具有访问所需端点的权限
## 连接问题
### 网络超时配置
服务器使用 HTTPX 进行 HTTP 请求，并通过 `HTTPX_TIMEOUT` 环境变量配置超时时间。
**超时配置源代码：**
```python
# servers/perplexity/server.py
HTTPX_TIMEOUT = httpx.Timeout(
connect=float(os.getenv("HTTPX_TIMEOUT", "30.0")),
read=float(os.getenv("HTTPX_TIMEOUT", "60.0")),
write=float(os.getenv("HTTPX_TIMEOUT", "30.0")),
pool=float(os.getenv("HTTPX_TIMEOUT", "30.0")),
)
资料来源：[servers/perplexity/server.py:45-50](https://github.com/mcparmory/registry/blob/main/servers/perplexity/server.py)
```
**超时问题排查：**
```mermaid
graph LR
A[请求发送] --> B{超时?}
B -->|是| C[检查网络连接]
B -->|否| D[正常处理]
C --> E[增加 HTTPX_TIMEOUT]
C --> F[检查防火墙设置]
C --> G[验证 BASE_URL]
```
### 连接池配置
服务器配置了连接池参数以优化并发性能：
| 参数 | 环境变量 | 默认值 | 说明 |
|------|----------|--------|------|
| 连接池大小 | `CONNECTION_POOL_SIZE` | 100 | 最大连接数 |
| 保持连接数 | `MAX_KEEPALIVE_CONNECTIONS` | 20 | 复用连接数 |
```python
CONNECTION_POOL_SIZE = int(os.getenv("CONNECTION_POOL_SIZE", "100"))
MAX_KEEPALIVE_CONNECTIONS = int(os.getenv("MAX_KEEPALIVE_CONNECTIONS", "20"))
资料来源：[servers/google-search-console/server.py:40-41](https://github.com/mcparmory/registry/blob/main/servers/google-search-console/server.py)
```
**连接池耗尽症状：**
- 长时间等待后请求超时
- 错误信息包含 "Connection pool"
**解决方案：**
1. 增加 `CONNECTION_POOL_SIZE` 值
2. 检查是否有连接泄漏
3. 考虑实现连接池监控
### BASE_URL 配置错误
每个服务器都有默认的 API 端点，但可以通过环境变量覆盖：
| 服务器 | 环境变量 | 默认值 |
|--------|----------|--------|
| Perplexity | `BASE_URL` | `https://api.perplexity.ai` |
| Google Search Console | `BASE_URL` | `https://searchconsole.googleapis.com` |
| Confluence | `BASE_URL` | `https://{your_domain}.atlassian.net/wiki` |
```python
BASE_URL = os.getenv("BASE_URL", "https://api.perplexity.ai")
资料来源：[servers/perplexity/server.py:42](https://github.com/mcparmory/registry/blob/main/servers/perplexity/server.py)
```
## 参数验证错误
### Pydantic 模型验证失败
服务器使用 Pydantic 进行参数验证。当传入无效参数时，会返回详细的验证错误信息。
**验证错误处理代码：**
```python
try:
_request = _models.GenerateLlMsTxtRequest(
body=_models.GenerateLlMsTxtRequestBody(url=url, max_urls=max_urls, show_full_text=show_full_text)
)
except pydantic.ValidationError as _validation_err:
logging.error(f"Parameter validation failed for generate_llms_txt: {_validation_err}")
raise ValueError(f"Invalid parameters: {_validation_err.errors()}") from _validation_err
资料来源：[servers/firecrawl/server.py:80-87](https://github.com/mcparmory/registry/blob/main/servers/firecrawl/server.py)
```
**常见验证错误类型：**
| 错误类型 | 原因 | 解决方案 |
|----------|------|----------|
| 类型错误 | 传入类型与预期不符 | 检查参数类型 |
| 范围超限 | 数值超出允许范围 | 参考 API 文档 |
| 必填字段缺失 | 缺少必需参数 | 添加缺失参数 |
| 格式错误 | 字符串格式不正确 | 验证输入格式 |
### 严格模式与宽松模式
服务器使用两种验证模型：
```python
from _validators import PermissiveModel, StrictModel
```
| 模型 | 用途 | 行为 |
|------|------|------|
| `StrictModel` | 请求参数验证 | 严格类型检查 |
| `PermissiveModel` | 响应处理 | 允许额外字段 |
```python
class ChatCompletionsChatCompletionsPostRequestBodyWebSearchOptionsUserLocation(StrictModel):
latitude: float | None = Field(default=None, ...)
longitude: float | None = Field(default=None, ...)
资料来源：[servers/perplexity/_models.py:20-25](https://github.com/mcparmory/registry/blob/main/servers/perplexity/_models.py)
```
## 环境配置问题
### .env 文件配置
服务器支持通过 `.env` 文件加载本地配置：
```python
try:
from dotenv import load_dotenv
_env_path = Path(__file__).parent / '.env'
if _env_path.exists():
load_dotenv(_env_path)
except ImportError:
pass
资料来源：[servers/atlassian-confluence/server.py:30-35](https://github.com/mcparmory/registry/blob/main/servers/atlassian-confluence/server.py)
```
**标准 .env 文件结构：**
```env
# 认证配置
PERPLEXITY_API_KEY=your_api_key_here
# 连接配置
BASE_URL=https://api.perplexity.ai
HTTPX_TIMEOUT=60.0
CONNECTION_POOL_SIZE=100
# 日志配置
LOG_LEVEL=INFO
```
### 日志级别配置
通过 `LOG_LEVEL` 环境变量控制日志详细程度：
```python
LOG_LEVEL = os.getenv("LOG_LEVEL", "INFO").upper()
if LOG_LEVEL not in ("DEBUG", "INFO", "WARNING", "ERROR"):
LOG_LEVEL = "INFO"
资料来源：[servers/perplexity/server.py:52-55](https://github.com/mcparmory/registry/blob/main/servers/perplexity/server.py)
```
| 日志级别 | 用途 | 输出内容 |
|----------|------|----------|
| `DEBUG` | 详细调试 | 所有请求/响应详情 |
| `INFO` | 一般信息 | 操作状态摘要 |
| `WARNING` | 警告信息 | 非致命问题 |
| `ERROR` | 错误信息 | 仅错误信息 |
## 运行时异常
### 依赖缺失
服务器依赖以下核心库：
| 依赖 | 用途 | 常见错误 |
|------|------|----------|
| `fastmcp` | MCP 服务器框架 | 导入错误 |
| `httpx` | HTTP 客户端 | 连接失败 |
| `pydantic` | 数据验证 | 模型错误 |
| `python-dotenv` | 环境变量加载 | 配置缺失 |
### 服务器版本不兼容
检查服务器版本兼容性：
```json
{
"$schema": "https://static.modelcontextprotocol.io/schemas/2025-12-11/server.schema.json",
"name": "com.mcparmory/e2b",
"version": "1.0.5",
"repository": {
"url": "https://github.com/mcparmory/registry",
"source": "github"
}
资料来源：[servers/e2b/server.json:1-10](https://github.com/mcparmory/registry/blob/main/servers/e2b/server.json)
```
## 调试流程图
```mermaid
flowchart TD
A[开始调试] --> B[检查日志级别]
B --> C{是否可见错误?}
C -->|否| D[提升日志级别到 DEBUG]
D --> E[重新运行操作]
C -->|是| F[分析错误信息]
F --> G{错误类型判断}
G -->|认证错误| H[验证 API 密钥]
G -->|连接错误| I[检查网络和 BASE_URL]
G -->|验证错误| J[检查参数类型和范围]
G -->|配置错误| K[检查环境变量]
H --> L{问题解决?}
I --> L
J --> L
K --> L
L -->|是| M[问题解决]
L -->|否| N[查看源码定位问题]
N --> O[提交 Issue 或 PR]
```
## 常用诊断命令
### 验证服务器配置
```bash
# 检查 Python 版本
python3 --version
# 验证依赖安装
pip list | grep -E "fastmcp|httpx|pydantic"
# 测试服务器启动
python3 servers/perplexity/server.py --help
```
### 检查环境变量
```bash
# 列出所有相关环境变量
env | grep -E "API_KEY|BASE_URL|LOG_LEVEL|HTTPX"
# 加载 .env 文件并检查
source .env && echo $PERPLEXITY_API_KEY
```
## 社区常见问题
根据社区讨论，用户在使用 MCP 服务器时常遇到以下问题：
1. **上下文膨胀问题**：用户反馈使用 MEMORY.md 等文件导致上下文过大。本项目的轻量级 MCP 服务器可以帮助减少上下文负担。
2. **服务器管理复杂性**：用户需要一个 GUI 工具来管理多个 MCP 服务器。本项目的 registry 提供了标准化的服务器配置格式。
## 相关文档
- [MCP 服务器列表](./服务器列表)
- [快速入门指南](./快速入门)
- [认证配置](./认证配置)
- [服务器开发](./开发指南)
---
*本文档由 MCP Blacksmith 自动生成，基于 mcparmory/registry 源码版本构建。*
---
## 贡献指南
### 相关页面
相关主题：[项目介绍](#page-introduction), [服务器标准模式](#page-server-pattern)
相关源码文件
以下源码文件用于生成本页说明：
- [README.md](https://github.com/mcparmory/registry/blob/main/README.md)
- [servers/perplexity/server.json](https://github.com/mcparmory/registry/blob/main/servers/perplexity/server.json)
- [servers/perplexity/server.py](https://github.com/mcparmory/registry/blob/main/servers/perplexity/server.py)
- [servers/e2b/server.json](https://github.com/mcparmory/registry/blob/main/servers/e2b/server.json)
- [servers/perigon/server.py](https://github.com/mcparmory/registry/blob/main/servers/perigon/server.py)
- [servers/firecrawl/server.py](https://github.com/mcparmory/registry/blob/main/servers/firecrawl/server.py)
- [servers/atlassian-confluence/server.py](https://github.com/mcparmory/registry/blob/main/servers/atlassian-confluence/server.py)
# 贡献指南
本项目是一个开源的 MCP（Model Context Protocol）服务器注册表，旨在为 AI 代理提供统一的工具和服务集成。本指南将帮助您了解如何为该项目贡献新的服务器或改进现有功能。
## 项目概述
mcparmory/registry 是一个集中管理 MCP 服务器的开源项目，每个服务器都是一个独立的 PyPI 包，可以独立安装和运行。项目采用标准化的服务器定义格式，确保所有服务器都能通过统一的接口进行调用和管理。
根据 README.md 的说明，该注册表涵盖了多个服务类别，包括但不限于开发工具、通信平台、云服务、内容管理系统等。
## 贡献方式
### 添加新服务器
向注册表添加新服务器是最常见的贡献方式。每个服务器都需要遵循统一的项目结构：
```mermaid
graph TD
A[新增服务器目录] --> B[创建 server.json 元数据]
B --> C[创建 server.py 主程序]
C --> D[创建 _models.py 数据模型]
D --> E[创建 _auth.py 认证模块]
E --> F[创建 .env.example 环境变量示例]
F --> G[提交 Pull Request]
```
### 服务器目录结构
每个 MCP 服务器必须包含以下核心文件：
| 文件名 | 必需 | 说明 |
|--------|------|------|
| `server.json` | ✅ | 服务器元数据和包配置 |
| `server.py` | ✅ | 主程序入口，实现 MCP 工具 |
| `_models.py` | ✅ | Pydantic 数据模型定义 |
| `_auth.py` | ✅ | 认证方式和端点映射 |
| `.env.example` | 建议 | 环境变量配置示例 |
| `README.md` | 建议 | 服务器使用文档 |
## 服务器配置规范
### server.json 结构
每个服务器根目录下必须包含 `server.json` 文件，定义服务器的元数据和包信息：
```json
{
"$schema": "https://static.modelcontextprotocol.io/schemas/2025-12-11/server.schema.json",
"name": "com.mcparmory/",
"description": "服务器功能描述",
"version": "1.0.0",
"repository": {
"url": "https://github.com/mcparmory/registry",
"source": "github"
},
"packages": [
{
"registryType": "pypi",
"identifier": "mcparmory-",
"version": "1.0.0",
"runtimeHint": "uvx",
"transport": {
"type": "stdio"
}
},
{
"registryType": "oci",
"identifier": "ghcr.io/mcparmory/:1.0.0",
"runtimeHint": "docker",
"transport": {
"type": "stdio"
}
}
]
}
```
**关键字段说明：**
| 字段 | 说明 | 示例值 |
|------|------|--------|
| `name` | 服务器唯一标识符 | `com.mcparmory/perplexity` |
| `version` | 语义化版本号 | `1.0.2` |
| `registryType` | 包类型 | `pypi` 或 `oci` |
| `runtimeHint` | 运行时提示 | `uvx` 或 `docker` |
| `transport.type` | 传输协议 | `stdio` |
### 包注册要求
服务器需要同时提供 PyPI 和 OCI（容器镜像）两种分发方式：
**PyPI 包配置：**
- 包名格式：`mcparmory-`
- 运行时提示：`uvx`
- 适合本地开发和测试
**OCI 镜像配置：**
- 镜像地址格式：`ghcr.io/mcparmory/:`
- 运行时提示：`docker`
- 适合生产环境部署
## server.py 实现规范
### 基本框架
所有服务器主程序都遵循统一的实现模式，基于 FastMCP 框架构建：
```python
#!/usr/bin/env python3
"""
MCP Server
Generated:
Generator: MCP Blacksmith v1.1.0 (https://mcpblacksmith.com)
"""
from __future__ import annotations
import argparse
import asyncio
import logging
import os
from pathlib import Path
try:
from dotenv import load_dotenv
_env_path = Path(__file__).parent / '.env'
if _env_path.exists():
load_dotenv(_env_path)
except ImportError:
pass
import _auth
import _models
import httpx
from fastmcp import FastMCP
from fastmcp.tools import ToolResult
BASE_URL = os.getenv("BASE_URL", "https://api.example.com")
SERVER_NAME = ""
SERVER_VERSION = "1.0.0"
CONNECTION_POOL_SIZE = int(os.getenv("CONNECTION_POOL_SIZE", "100"))
MAX_KEEPALIVE_CONNECTIONS = int(os.getenv("MAX_KEEPALIVE_CONNECTIONS", "20"))
LOG_LEVEL = os.getenv("LOG_LEVEL", "INFO").upper()
mcp = FastMCP(SERVER_NAME)
```
**环境变量配置：**
| 变量名 | 默认值 | 说明 |
|--------|--------|------|
| `BASE_URL` | API 基础 URL | 必需的环境配置 |
| `CONNECTION_POOL_SIZE` | `100` | HTTP 连接池大小 |
| `MAX_KEEPALIVE_CONNECTIONS` | `20` | 最大保活连接数 |
| `LOG_LEVEL` | `INFO` | 日志级别 |
| `HTTPX_TIMEOUT` | 视实现而定 | HTTP 请求超时时间 |
### 工具定义模式
服务器通过装饰器模式定义可用的 MCP 工具：
```python
@mcp.tool()
async def your_tool_name(
param1: str = Field(..., description="参数说明"),
param2: int | None = Field(None, description="可选参数")
) -> dict[str, Any] | ToolResult:
"""工具功能描述，用于 AI 模型理解工具用途"""
# 参数验证
try:
_request = _models.YourModelRequest(
body=_models.YourModelRequestBody(param1=param1, param2=param2)
)
except pydantic.ValidationError as _validation_err:
logging.error(f"参数验证失败: {_validation_err}")
raise ValueError(f"无效参数: {_validation_err.errors()}") from _validation_err
# 构建请求
_http_path = "/api/endpoint"
_http_body = _request.body.model_dump(by_alias=True, exclude_none=True)
_http_headers = {}
# 注入认证
_auth = await _get_auth_for_operation("your_operation")
# 发送请求
async with httpx.AsyncClient(timeout=HTTPX_TIMEOUT) as _client:
_response = await _client.request(
method="POST",
url=f"{BASE_URL}{_http_path}",
json=_http_body,
headers=_http_headers,
auth=_auth
)
return _response.json()
```
### 认证模块 (_auth.py)
认证模块定义了每个 API 操作所需的认证方式：
```python
OPERATION_AUTH = {
"create_resource": [["ApiKey"]],
"get_resource": [["ApiKey"]],
"update_resource": [["ApiKey"], ["OAuth2"]],
"delete_resource": [["ApiKey"]],
"list_resources": [["ApiKey"], ["BearerAuth"]],
}
```
支持的认证类型包括：
| 认证类型 | 说明 | 适用场景 |
|----------|------|----------|
| `ApiKey` | API 密钥认证 | 大多数 REST API |
| `BearerAuth` | Bearer Token | OAuth2 访问令牌 |
| `BasicAuth` | 基本认证 | 简单身份验证 |
| `OAuth2` | OAuth2 认证 | 需要授权流程的 API |
| `PersonalAPIKeyAuth` | 个人 API 密钥 | Perplexity 等平台 |
## 数据模型规范 (_models.py)
### 模型基类
项目使用 Pydantic 定义请求和响应模型，提供两种验证模式：
```python
from _validators import PermissiveModel, StrictModel
from pydantic import Field
class CreateResourceRequest(StrictModel):
"""创建资源请求模型 - 严格验证所有字段"""
name: str = Field(..., description="资源名称")
type: str = Field(..., description="资源类型")
class GetResourceResponse(PermissiveModel):
"""获取资源响应模型 - 宽松验证，允许额外字段"""
id: str = Field(..., description="资源 ID")
status: str = Field(..., description="资源状态")
```
### 模型导出规范
每个 `_models.py` 文件必须定义 `__all__` 列表，明确导出所有公共模型：
```python
__all__ = [
"CreateResourceRequest",
"CreateResourceResponse",
"ListResourcesRequest",
"ListResourcesResponse",
"ResourceModel",
]
```
## 提交规范
### Pull Request 检查清单
在提交 PR 之前，请确保完成以下检查：
1. **代码结构检查**
- [ ] 遵循服务器目录结构规范
- [ ] 包含所有必需文件（server.json, server.py, _models.py, _auth.py）
- [ ] 所有 Python 文件包含正确的 shebang 和文档字符串
2. **配置文件检查**
- [ ] server.json 符合 JSON Schema 规范
- [ ] 版本号遵循语义化版本（SemVer）
- [ ] 包含 PyPI 和 OCI 两种包定义
3. **代码质量检查**
- [ ] 所有工具函数包含完整的类型注解
- [ ] 参数描述使用 Pydantic Field 的 description
- [ ] 错误处理覆盖所有可能的异常情况
- [ ] 日志记录使用标准 logging 模块
4. **认证配置检查**
- [ ] _auth.py 正确定义所有操作的认证方式
- [ ] 支持多种认证方式的操作已正确映射
### 提交信息规范
使用清晰明了的提交信息：
```
feat: 添加 Perplexity MCP 服务器支持
fix: 修复 Google Analytics 连接池泄漏问题
docs: 更新 README.md 服务器列表
refactor: 重构认证模块支持多认证方式
```
## 服务器分类参考
当前注册表涵盖以下服务类别，可作为新增服务器的参考：
| 类别 | 示例服务器 | 说明 |
|------|------------|------|
| 通信 | Slack, Discord | 即时通讯平台 |
| 开发 | GitHub, GitLab | 代码托管和协作 |
| 搜索 | Algolia, Perplexity | 搜索和发现服务 |
| 云服务 | AWS, Google Cloud | 基础设施服务 |
| 内容管理 | Notion, Confluence | 文档和知识管理 |
| 分析 | Google Analytics | 数据分析平台 |
| 安全 | PagerDuty | 监控和告警服务 |
## 常见问题
### Q: 如何测试新添加的服务器？
A: 使用 `uvx` 直接运行服务器进行本地测试：
```bash
uvx mcparmory-
```
### Q: 是否支持自定义 BASE_URL？
A: 是的，所有服务器都支持通过环境变量自定义 API 端点：
```bash
export BASE_URL="https://custom-api.example.com"
```
### Q: 如何处理需要 OAuth2 认证的 API？
A: 在 _auth.py 中定义 OAuth2 认证方式，并在 server.py 中实现完整的授权流程。参考现有服务器的 OAuth2 实现模式。
## 相关资源
- [官方 MCP 协议文档](https://modelcontextprotocol.io)
- [FastMCP 框架文档](https://github.com/jlowin/fastmcp)
- [MCP Blacksmith 代码生成器](https://mcpblacksmith.com)
- [PyPI 包发布指南](https://packaging.python.org/tutorials/packaging-projects/)
---
---
## Doramagic 踩坑日志
项目：mcparmory/registry
摘要：发现 7 个潜在踩坑项，其中 0 个为 high/blocking；最高优先级：身份坑 - 仓库名和安装名不一致。
## 1. 身份坑 · 仓库名和安装名不一致
- 严重度：medium
- 证据强度：runtime_trace
- 发现：仓库名 `registry` 与安装入口 `mcparmory-contentful-management` 不完全一致。
- 对用户的影响：用户照着仓库名搜索包或照着包名找仓库时容易走错入口。
- 建议检查：在 npm/PyPI/GitHub 上确认包名映射和官方 README 说明。
- 复现命令：`uvx mcparmory-contentful-management`
- 防护动作：页面必须同时展示 repo 名和真实安装入口，避免用户搜索错包。
- 证据：identity.distribution | mcp_registry:com.mcparmory/contentful-management:1.0.3 | https://registry.modelcontextprotocol.io/v0.1/servers/com.mcparmory%2Fcontentful-management/versions/1.0.3 | repo=registry; install=mcparmory-contentful-management
## 2. 能力坑 · 能力判断依赖假设
- 严重度：medium
- 证据强度：source_linked
- 发现：README/documentation is current enough for a first validation pass.
- 对用户的影响：假设不成立时，用户拿不到承诺的能力。
- 建议检查：将假设转成下游验证清单。
- 防护动作：假设必须转成验证项；没有验证结果前不能写成事实。
- 证据：capability.assumptions | mcp_registry:com.mcparmory/contentful-management:1.0.3 | https://registry.modelcontextprotocol.io/v0.1/servers/com.mcparmory%2Fcontentful-management/versions/1.0.3 | README/documentation is current enough for a first validation pass.
## 3. 维护坑 · 维护活跃度未知
- 严重度：medium
- 证据强度：source_linked
- 发现：未记录 last_activity_observed。
- 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。
- 建议检查：补 GitHub 最近 commit、release、issue/PR 响应信号。
- 防护动作：维护活跃度未知时，推荐强度不能标为高信任。
- 证据：evidence.maintainer_signals | mcp_registry:com.mcparmory/contentful-management:1.0.3 | https://registry.modelcontextprotocol.io/v0.1/servers/com.mcparmory%2Fcontentful-management/versions/1.0.3 | last_activity_observed missing
## 4. 安全/权限坑 · 下游验证发现风险项
- 严重度：medium
- 证据强度：source_linked
- 发现：no_demo
- 对用户的影响：下游已经要求复核，不能在页面中弱化。
- 建议检查：进入安全/权限治理复核队列。
- 防护动作：下游风险存在时必须保持 review/recommendation 降级。
- 证据：downstream_validation.risk_items | mcp_registry:com.mcparmory/contentful-management:1.0.3 | https://registry.modelcontextprotocol.io/v0.1/servers/com.mcparmory%2Fcontentful-management/versions/1.0.3 | no_demo; severity=medium
## 5. 安全/权限坑 · 存在评分风险
- 严重度：medium
- 证据强度：source_linked
- 发现：no_demo
- 对用户的影响：风险会影响是否适合普通用户安装。
- 建议检查：把风险写入边界卡，并确认是否需要人工复核。
- 防护动作：评分风险必须进入边界卡，不能只作为内部分数。
- 证据：risks.scoring_risks | mcp_registry:com.mcparmory/contentful-management:1.0.3 | https://registry.modelcontextprotocol.io/v0.1/servers/com.mcparmory%2Fcontentful-management/versions/1.0.3 | no_demo; severity=medium
## 6. 维护坑 · issue/PR 响应质量未知
- 严重度：low
- 证据强度：source_linked
- 发现：issue_or_pr_quality=unknown。
- 对用户的影响：用户无法判断遇到问题后是否有人维护。
- 建议检查：抽样最近 issue/PR，判断是否长期无人处理。
- 防护动作：issue/PR 响应未知时，必须提示维护风险。
- 证据：evidence.maintainer_signals | mcp_registry:com.mcparmory/contentful-management:1.0.3 | https://registry.modelcontextprotocol.io/v0.1/servers/com.mcparmory%2Fcontentful-management/versions/1.0.3 | issue_or_pr_quality=unknown
## 7. 维护坑 · 发布节奏不明确
- 严重度：low
- 证据强度：source_linked
- 发现：release_recency=unknown。
- 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。
- 建议检查：确认最近 release/tag 和 README 安装命令是否一致。
- 防护动作：发布节奏未知或过期时，安装说明必须标注可能漂移。
- 证据：evidence.maintainer_signals | mcp_registry:com.mcparmory/contentful-management:1.0.3 | https://registry.modelcontextprotocol.io/v0.1/servers/com.mcparmory%2Fcontentful-management/versions/1.0.3 | release_recency=unknown