概述

mcparmory/registry 是一个开源的 MCP (Model Context Protocol) 服务器注册表仓库，托管在 GitHub 上，旨在为 AI Agent 提供统一管理的工具集成解决方案。该项目通过标准化的 MCP 服务器实现，让 AI Agent 能够以一致的方式调用外部服务和 API，从而避免在 Agent 上下文 (context) 中堆积大量配置信息导致的"上下文膨胀"问题。

资料来源：README.md

核心价值与定位

在现代 AI Agent 应用开发中，一个常见的痛点是需要为 Agent 配置大量的外部工具和 API 连接。这些配置通常以 MEMORY.md 或类似文件的形式存在，随着工具数量的增加，导致 Agent 的上下文窗口被大量占用，严重影响推理效率和成本。

mcparmory/registry 项目通过以下方式解决这一问题：

资料来源：servers/perplexity/server.json

架构设计

整体架构

MCP 服务器注册表采用分层架构设计，核心组件包括：

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/ 目录下独立存在，形成统一的目录结构：

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]

技术栈

资料来源：servers/perplexity/server.py:1-30

服务器类型

搜索与信息获取类

资料来源：servers/perplexity/server.json、servers/google-search-console/server.py

协作与内容管理类

资料来源：servers/atlassian-confluence/server.py:1-40

开发运维类

资料来源：servers/pagerduty/server.json

AI 与安全类

资料来源：servers/e2b/server.json

服务器配置格式

server.json 配置结构

每个 MCP 服务器都包含一个标准化的 server.json 配置文件，遵循 MCP 协议规范：

{
  "$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

配置字段说明

认证机制

支持的认证类型

MCP 服务器通过 _auth.py 模块实现灵活的认证机制：

资料来源：servers/atlassian-confluence/_auth.py

认证配置示例

# 服务端使用 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

数据模型

模型层架构

服务器使用 Pydantic 定义严格的数据模型，确保 API 请求和响应的类型安全：

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]

模型类型

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

工具定义模式

工具装饰器

每个 MCP 工具使用 @mcp.tool() 装饰器定义，包含元数据注解：

@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

工具注解说明

资料来源：servers/atlassian-confluence/server.py

HTTP 客户端配置

连接池管理

服务器使用 httpx 实现高性能异步 HTTP 通信：

# 连接池配置
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
)

资料来源：servers/google-search-console/server.py:35-50

部署方式

uvx 运行时部署

通过 uvx 直接运行 PyPI 包：

uvx mcparmory-perplexity

Docker 运行时部署

通过容器镜像运行：

docker run ghcr.io/mcparmory/perplexity:1.0.2

环境变量配置

常见使用场景

场景一：AI Agent 搜索增强

AI Agent 可以通过 perplexity 或 google-search-console 服务器实现实时网页搜索能力：

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 服务器实现仓库管理和自动化工作流：

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 生成的代码：

# 使用 e2b 服务器执行代码
result = await e2b_sandbox.execute(code="print('Hello World')")

版本兼容性

所有服务器遵循统一的 MCP 协议 schema 版本，确保跨服务器的一致性和兼容性。

与社区的关系

根据 Reddit 社区讨论，本项目解决了 AI Agent 开发中的关键痛点：

"Stop bloating your agent context with MEMORY.md. I built a local registry..."

本注册表项目作为开源替代方案，让开发者可以在本地管理 MCP 服务器，避免依赖外部服务，同时减少 Agent 上下文的膨胀问题。

资料来源：Reddit 社区讨论

参与贡献

添加新服务器

1. 在 servers/ 目录下创建新服务器目录
2. 添加 server.json 配置文件
3. 使用 MCP Blacksmith 生成服务器代码
4. 实现 _auth.py 认证模块
5. 测试并提交 PR

代码规范

• 使用 Pydantic StrictModel 进行数据验证
• 遵循 PEP 8 代码风格
• 所有工具函数使用 async/await
• 提供完整的中英文文档字符串

参见

• MCP 协议规范
• FastMCP 框架
• MCP Blacksmith 代码生成器
• 官方服务器注册表

概述

mcparmory/registry 是一个开源的 MCP（Model Context Protocol）服务器注册中心，托管在 GitHub 上。该仓库汇集了多种第三方服务的 MCP 服务器实现，为 AI 代理提供标准化的工具调用接口。通过统一的注册机制，开发者可以快速发现、配置和部署所需的 MCP 服务器。

根据社区反馈，类似这样的本地注册中心可以帮助 AI Agent 避免上下文膨胀问题，使用本地配置文件替代在每次对话中传递 MEMORY.md 的方式。Reddit - Stop bloating your agent context with MEMORY.md

架构设计

注册中心整体架构

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 服务器运行时架构

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

服务器分类

按功能分类

服务器标识符命名规范

所有服务器遵循反向域名命名约定：

com.mcparmory/{服务名}

资料来源：servers/perplexity/server.json:2

服务端点与工具

Perplexity 服务器工具

Perplexity MCP 服务器提供以下核心功能：

资料来源：servers/perplexity/_models.py:1-30

E2B 沙箱服务器

E2B 服务器为 AI Agent 提供安全的代码执行环境：

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

Confluence 服务器功能

Atlassian Confluence MCP 服务器提供丰富的文档管理功能：

资料来源：servers/atlassian-confluence/server.py:1-100

认证机制

支持的认证类型

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）：

"create_insight_sharing_password": [["PersonalAPIKeyAuth"]],
"list_insight_thresholds": [["PersonalAPIKeyAuth"]],
"get_insight": [["PersonalAPIKeyAuth"]],
"update_insight": [["PersonalAPIKeyAuth"]],
"annotations_destroy": [["PersonalAPIKeyAuth"]],

资料来源：servers/posthog/_auth.py:1-30

Canvas LMS 认证配置（OAuth2 + Bearer）：

"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

包分发配置

server.json 结构

每个服务器都包含标准的 server.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

包类型对比

传输协议

所有服务器统一使用 stdio 传输类型：

graph LR
    A[主机进程] -->|stdin| B[MCP Server]
    B -->|stdout| A

资料来源：servers/linkup/server.json:15-20

数据模型

Pydantic 模型架构

服务器使用 Pydantic 进行请求/响应数据验证：

classDiagram
    class StrictModel {
        <<基类>>
        +严格字段验证
        +必填字段检查
    }
    class PermissiveModel {
        <<基类>>
        +宽松字段验证
        +可选字段处理
    }
    class *Request {
        +path: PathParams
        +query: QueryParams
        +body: RequestBody
    }
    class *Response {
        +数据验证
        +类型转换
    }
    
    StrictModel <|-- *Request
    PermissiveModel <|-- *Request

模型导出示例

__all__ = [
    "SearchArticlesRequest",
    "SearchCompaniesRequest",
    "SearchJournalistsRequest",
    "SearchStoriesRequest",
    "VectorSearchArticlesRequest",
]

资料来源：servers/perigon/_models.py:1-25

Ragie 连接配置模型

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

快速入门

环境要求

安装方式

方式一：通过 uvx 运行

uvx mcparmory-{服务名}

方式二：通过 Docker 运行

docker run ghcr.io/mcparmory/{服务名}:{版本}

方式三：pip 安装

pip install mcparmory-{服务名}

环境配置

在服务器目录下创建 .env 文件：

# 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

常见故障排查

认证错误

连接问题

数据验证错误

# 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

扩展新的服务器

添加新服务器的步骤

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：

"$schema": "https://static.modelcontextprotocol.io/schemas/2025-12-11/server.schema.json"

资料来源：servers/pagerduty/server.json:2

参考链接

相关主题

• 服务器快速开始指南
• 认证配置详解
• 包分发机制
• 贡献新服务器

概述

MCP 服务器标准模式是一套统一的架构约定和实现规范，用于构建与 Model Context Protocol 兼容的服务器组件。每个服务器都遵循相同的项目结构、传输协议、认证机制和错误处理流程。

资料来源：servers/perplexity/server.py:1-30

核心架构

整体架构图

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

技术栈组件

资料来源：servers/atlassian-confluence/server.py:39-52

项目结构规范

每个 MCP 服务器遵循统一的项目目录结构：

servers/<server-name>/
├── server.py          # 主服务器实现
├── server.json        # 服务器元数据
├── _auth.py           # 认证配置
├── _models.py         # Pydantic 模型定义
├── _validators.py     # 自定义验证器
├── pyproject.toml     # Python 项目配置
├── .env               # 环境变量（可选）
└── README.md          # 文档说明

资料来源：servers/perplexity/server.json

服务器配置规范

server.json 配置结构

每个服务器的 server.json 文件定义了其元数据和分发包信息：

{
  "$schema": "https://static.modelcontextprotocol.io/schemas/2025-12-11/server.schema.json",
  "name": "com.mcparmory/<server-name>",
  "description": "服务器功能描述",
  "version": "1.0.0",
  "repository": {
    "url": "https://github.com/mcparmory/registry",
    "source": "github"
  },
  "packages": [
    {
      "registryType": "pypi",
      "identifier": "mcparmory-<server-name>",
      "version": "1.0.0",
      "runtimeHint": "uvx",
      "transport": {
        "type": "stdio"
      }
    },
    {
      "registryType": "oci",
      "identifier": "ghcr.io/mcparmory/<server-name>:1.0.0",
      "runtimeHint": "docker",
      "transport": {
        "type": "stdio"
      }
    }
  ]
}

资料来源：servers/perplexity/server.json

配置参数说明

资料来源：servers/e2b/server.json

服务器初始化模式

标准初始化流程

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: 服务器就绪

环境变量配置

所有服务器支持通过环境变量进行配置：

资料来源：servers/perplexity/server.py:55-75

核心初始化代码模式

# 环境变量加载
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

认证机制

认证架构

每个服务器拥有独立的认证模块 _auth.py，定义操作级别的认证策略：

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"]

认证类型支持

资料来源：servers/posthog/_auth.py:1-50

操作级认证配置

认证模块使用字典结构映射每个操作的认证方法：

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

工具定义模式

工具装饰器使用

所有工具通过 FastMCP 的 @mcp.tool() 装饰器定义：

@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

工具参数验证流程

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["异常处理"]

工具实现标准模板

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

数据模型规范

模型定义模式

使用 Pydantic v2 定义请求和响应模型：

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

验证器模式

资料来源：servers/ragie/_models.py:1-50

字段别名处理

class RequestQuery(StrictModel):
    # validation_alias: API 接收的参数名
    # serialization_alias: 序列化时使用的名称
    page_size: int | None = Field(
        default=None,
        validation_alias="pageSize",
        serialization_alias="page_size",
        description="分页大小参数"
    )

工具注解说明

annotations=ToolAnnotations(
    readOnlyHint=True,   # 不修改外部状态
    openWorldHint=True    # 调用外部 API
)

资料来源：servers/e2b/server.py

分发包配置

PyPI 分发配置

{
  "registryType": "pypi",
  "identifier": "mcparmory-<server-name>",
  "version": "1.0.0",
  "runtimeHint": "uvx",
  "transport": {
    "type": "stdio"
  }
}

Docker/OCI 分发配置

{
  "registryType": "oci",
  "identifier": "ghcr.io/mcparmory/<server-name>:1.0.0",
  "runtimeHint": "docker",
  "transport": {
    "type": "stdio"
  }
}

资料来源：servers/linkup/server.json

连接池配置

所有服务器统一使用 httpx 进行 HTTP 通信，并配置连接池参数：

CONNECTION_POOL_SIZE = int(os.getenv("CONNECTION_POOL_SIZE", "100"))
MAX_KEEPALIVE_CONNECTIONS = int(os.getenv("MAX_KEEPALIVE_CONNECTIONS", "20"))

常见故障模式

1. 环境变量未加载

# 症状：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. 参数验证失败

# 症状：抛出 ValueError，提示参数无效
# 解决：检查 Pydantic 模型的字段约束
try:
    _request = _models.SomeRequest(...)
except pydantic.ValidationError as _validation_err:
    logging.error(f"参数验证失败: {_validation_err}")
    raise ValueError(f"无效参数: {_validation_err.errors()}")

3. 认证配置缺失

# 症状：API 请求返回 401 Unauthorized
# 解决：确保环境变量中设置了正确的认证凭据
_auth = await _get_auth_for_operation("operation_name")
if not _auth:
    raise ValueError(f"操作 {operation_name} 缺少认证配置")

4. 连接池耗尽

# 症状：高并发时请求阻塞或超时
# 解决：增大 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 协议规范
• FastMCP 框架文档
• Pydantic v2 文档

概述

MCP Registry 项目中的 MCP 服务器（Model Context Protocol Server）实现了统一的认证机制，用于在 AI 代理与外部服务之间建立安全连接。每个服务器都拥有独立的 _auth.py 认证模块，负责将具体的 API 操作映射到相应的认证方法。

这种设计遵循了每个服务一个认证配置的原则，使得认证逻辑与业务逻辑分离，便于维护和扩展。开发者可以根据不同服务的 API 安全要求，灵活配置所需的认证方式。

认证类型体系

MCP Registry 支持多种认证类型，以满足不同外部服务的安全要求。根据源码分析，当前系统支持以下认证方式：

资料来源：servers/canvas/_auth.py

认证配置结构

认证映射机制

每个服务器的 _auth.py 文件导出一个字典结构，将操作名称映射到所需的认证类型列表。这种映射方式允许同一操作支持多种认证方式，提高了系统的兼容性。

# 认证映射示例
OPERATION_AUTH = {
    "operation_name": [["AuthType1"], ["AuthType2"]],
    "list_pull_requests": [["OAuth2"], ["PersonalAccessToken"]],
}

在上述结构中，operation_name 对应的列表可以包含多个认证方案，每个方案作为一个独立的列表元素。当第一个认证方案不可用时，系统可以回退到下一个方案。

资料来源：servers/github/_auth.py

认证数据结构

认证配置采用嵌套列表结构，支持多认证方案定义。每个操作的认证需求以列表形式存储，便于系统按顺序尝试不同的认证方法。

graph TD
    A[API 操作请求] --> B{查找认证配置}
    B --> C[获取认证方案列表]
    C --> D[尝试第一个认证方案]
    D --> E{认证成功?}
    E -->|是| F[执行操作]
    E -->|否| G[尝试下一个认证方案]
    G --> H{还有更多方案?}
    H -->|是| D
    H -->|否| I[返回认证失败]

认证流程详解

请求级别的认证注入

认证信息的注入发生在 HTTP 请求层面。当执行工具请求时，系统会根据操作名称从 _auth.py 获取所需的认证类型，然后从配置或环境变量中提取相应的凭证。

# 从源码中提取的认证注入流程
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

多认证方案回退机制

系统支持认证方案的回退机制。当主认证方案失效或不可用时，系统会自动尝试备选方案，确保请求能够成功执行。

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 操作等场景。

资料来源：servers/github/_auth.py

Canvas LMS 服务认证

Canvas 学习管理系统采用 OAuth2 和 Bearer Token 双重认证机制，确保教育平台数据访问的安全性。

# 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

PostHog 分析平台认证

PostHog 使用 PersonalAPIKeyAuth 进行认证，适用于产品分析、用户行为追踪、A/B 测试等数据驱动场景。

PostHog 的认证覆盖了从基础分析到高级实验的全部操作，确保产品数据分析的安全访问。

资料来源：servers/posthog/_auth.py

LaunchDarkly 服务认证

LaunchDarkly 采用简洁的 ApiKey 认证方式，适用于特性开关管理、环境配置、发布策略等 DevOps 场景。

# 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

环境变量配置

认证凭证存储

MCP 服务器通过环境变量存储敏感凭证信息，支持 .env 文件配置。每个服务器定义其所需的环境变量，遵循统一的安全最佳实践。

# 环境变量加载示例
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

常用环境变量

认证安全最佳实践

凭证管理建议

1. 敏感信息隔离：所有认证凭证应存储在环境变量或安全的密钥管理系统中，避免硬编码到源码
2. 最小权限原则：为不同操作分配适当的认证方式，确保只授予必要的访问权限
3. 凭证轮换：定期更换 API 密钥和个人访问令牌，减少凭证泄露风险
4. 日志脱敏：在日志输出时对敏感凭证进行脱敏处理，防止信息泄露

多认证方案的设计优势

MCP Registry 采用的多认证方案回退机制具有以下优势：

• 兼容性：支持同一服务在不同时期采用不同认证方式
• 容错性：主认证方案失败时可自动切换到备选方案
• 灵活性：便于新增认证方式而不影响现有功能
• 可维护性：认证逻辑集中管理，便于统一升级和修复

故障排查指南

常见认证错误

调试方法

1. 启用详细日志：设置 LOG_LEVEL=DEBUG 查看完整的认证流程
2. 验证凭证有效性：直接调用 API 确认凭证状态
3. 检查认证配置：确认 _auth.py 中的操作映射是否正确
4. 环境隔离测试：在干净环境中重新配置认证信息

架构总结

MCP Registry 的认证机制采用声明式配置 + 运行时注入的设计模式，将认证逻辑与业务逻辑完全解耦。这种设计使得：

• 每个服务可以独立定义其认证策略
• 新增认证类型时无需修改核心框架
• 认证方案的切换和扩展极为便捷
• 单元测试可以轻松模拟不同的认证场景

通过统一的认证抽象层，MCP Registry 能够安全地连接多种外部服务，为 AI 代理提供稳定可靠的数据访问能力。

概述

MCP Registry 的核心设计理念是每个服务器都是独立的 PyPI 包，遵循 Model Context Protocol 标准。服务器支持三种部署方式：

资料来源：README.md

支持的 MCP 客户端

部署完成的服务器可与以下客户端集成：

• Claude Desktop
• Cursor
• Codex
• Claude Code

环境准备

系统要求

安装 uvx（推荐用于快速启动）

uvx 是 uv 工具的即时执行模式，无需预先安装包即可运行：

# 使用 pip 安装 uv
pip install uv

# 或使用 curl 安装
curl -LsSf https://astral.sh/uv/install.sh | sh

部署方式

方式一：uvx 快速运行

uvx 模式适合快速测试和临时使用，服务器会自动下载并执行：

# 运行 GitHub 服务器
uvx mcparmory-github

# 运行 Perplexity 服务器
uvx mcparmory-perplexity

# 运行 Slack 服务器
uvx mcparmory-slack

资料来源：README.md

方式二：pip 安装

对于生产环境，建议使用 pip 将服务器安装到本地环境：

# 安装单个服务器
pip install mcparmory-github
pip install mcparmory-perplexity
pip install mcparmory-slack

# 安装后运行
mcparmory-github
mcparmory-perplexity

方式三：Docker 容器部署

每个服务器都提供了预构建的 Docker 镜像，支持 OCI 标准：

graph TD
    A[启动容器] --> B{镜像来源}
    B --> C[使用预构建镜像]
    B --> D[本地构建镜像]
    C --> E[配置环境变量]
    D --> E
    E --> F[连接到 MCP 客户端]

#### 预构建镜像使用

服务器配置中定义了标准化的 OCI 镜像：

{
  "registryType": "oci",
  "identifier": "ghcr.io/mcparmory/perplexity:1.0.2",
  "runtimeHint": "docker",
  "transport": {
    "type": "stdio"
  }
}

资料来源：servers/perplexity/server.json

#### 常用服务器镜像对照表

资料来源：servers/e2b/server.json、servers/pagerduty/server.json

MCP 客户端配置

Claude Desktop 配置

在 claude_desktop_config.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

通用 MCP 客户端配置模板

{
  "mcpServers": {
    "<server-name>": {
      "command": "uvx",
      "args": ["mcparmory-<server-name>"],
      "env": {
        "<ENV_VAR_NAME>": "<your-value>"
      }
    }
  }
}

环境变量配置

服务器通用配置

每个服务器支持以下通用环境变量：

资料来源：servers/perplexity/server.py

.env 文件配置

服务器支持通过 .env 文件加载环境变量：

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

创建 .env 文件示例：

# Perplexity 服务器配置
PERPLEXITY_API_KEY=pplx-your-api-key-here
LOG_LEVEL=DEBUG

# Confluence 服务器配置
CONFLUENCE_API_TOKEN=your-api-token
[email protected]
BASE_URL=https://your-domain.atlassian.net/wiki

认证配置

不同服务器支持多种认证方式：

服务器根据 OpenAPI 规范自动处理认证头的注入：

# 认证头由 _auth.py 模块统一管理
_auth = await _get_auth_for_operation("<operation-name>")

资料来源：servers/launchdarkly/_auth.py

部署架构

单服务器部署

适用于单一服务集成的简单场景：

graph LR
    A[MCP 客户端] -->|stdio| B[单个 MCP 服务器]
    B --> C[目标 API]

多服务器部署

生产环境通常需要同时运行多个服务器：

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 管理多服务器部署：

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 传输协议：

{
  "transport": {
    "type": "stdio"
  }
}

stdio 模式通过标准输入/输出流与客户端通信，适合本地和容器环境：

# 服务器启动时自动初始化 stdio 传输
from fastmcp import FastMCP

mcp = FastMCP(SERVER_NAME)
mcp.run(transport="stdio")

资料来源：servers/google-search-console/server.py

HTTP/SSE 传输（可选）

部分服务器支持 HTTP 服务器发送事件（SSE）传输，适用于 Web 集成场景。

故障排除

常见部署问题

日志调试

启用 DEBUG 级别日志获取详细调试信息：

# 通过环境变量启用
export LOG_LEVEL=DEBUG
uvx mcparmory-github

或在 Docker 中：

docker run -e LOG_LEVEL=DEBUG ghcr.io/mcparmory/github:latest

连接池调优

对于高并发场景，调整连接池参数：

export CONNECTION_POOL_SIZE=200
export MAX_KEEPALIVE_CONNECTIONS=50
uvx mcparmory-perplexity

安全最佳实践

1. 环境变量管理

• 敏感信息存储在 .env 文件中
• .env 文件添加到 .gitignore
• 使用密钥管理服务（如 AWS Secrets Manager）进行生产环境配置

1. 网络隔离

• 使用 Docker 网络隔离 MCP 服务器
• 配置防火墙规则限制 API 访问

1. 最小权限原则

• 为 API Token 设置最小必要权限
• 定期轮换密钥

1. 容器安全

• 使用非 root 用户运行容器
• 定期更新基础镜像

升级与维护

版本更新

# uvx 模式 - 重新运行即使用最新版本
uvx mcparmory-github

# pip 模式 - 升级到最新版本
pip install --upgrade mcparmory-github

# Docker 模式 - 拉取最新镜像
docker pull ghcr.io/mcparmory/github:latest

查看当前版本

# 服务器启动时会输出版本信息
uvx mcparmory-github --version

相关资源

• 快速开始指南
• 服务器列表
• 认证配置参考
• API 参考文档

参见

• 项目主页
• MCP 协议规范
• FastMCP 框架文档

配置参考

本文档详细介绍 MCP Registry 仓库中各服务器组件的配置方式、环境变量规范以及认证机制。所有服务器均基于 FastMCP 框架构建，遵循统一的配置模式。

常见问题概览

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 服务器为例：

资料来源：[servers/posthog/_auth.py:1-50](https://github.com/mcparmory/registry/blob/04af6ce3ff58fb74017a715ad66d987d4bef45c8/servers/posthog/_auth.py)

常见环境变量：

认证类型不匹配

不同的外部 API 支持不同的认证方式。服务器实现会为每个操作指定所需的认证类型。

认证类型配置示例：

资料来源：[servers/canvas/_auth.py:1-30](https://github.com/mcparmory/registry/blob/04af6ce3ff58fb74017a715ad66d987d4bef45c8/servers/canvas/_auth.py)

解决方案：

1. 确认外部服务使用的认证类型
2. 检查环境变量配置是否正确
3. 验证 API 密钥是否具有访问所需端点的权限

连接问题

网络超时配置

服务器使用 HTTPX 进行 HTTP 请求，并通过 HTTPX_TIMEOUT 环境变量配置超时时间。

超时配置源代码：

# 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/04af6ce3ff58fb74017a715ad66d987d4bef45c8/servers/perplexity/server.py)

超时问题排查：

graph LR
    A[请求发送] --> B{超时?}
    B -->|是| C[检查网络连接]
    B -->|否| D[正常处理]
    C --> E[增加 HTTPX_TIMEOUT]
    C --> F[检查防火墙设置]
    C --> G[验证 BASE_URL]

连接池配置

服务器配置了连接池参数以优化并发性能：

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/04af6ce3ff58fb74017a715ad66d987d4bef45c8/servers/google-search-console/server.py)

连接池耗尽症状：

• 长时间等待后请求超时
• 错误信息包含 "Connection pool"

解决方案：

1. 增加 CONNECTION_POOL_SIZE 值
2. 检查是否有连接泄漏
3. 考虑实现连接池监控

BASE_URL 配置错误

每个服务器都有默认的 API 端点，但可以通过环境变量覆盖：

BASE_URL = os.getenv("BASE_URL", "https://api.perplexity.ai")

资料来源：[servers/perplexity/server.py:42](https://github.com/mcparmory/registry/blob/04af6ce3ff58fb74017a715ad66d987d4bef45c8/servers/perplexity/server.py)

参数验证错误

Pydantic 模型验证失败

服务器使用 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 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/04af6ce3ff58fb74017a715ad66d987d4bef45c8/servers/firecrawl/server.py)

常见验证错误类型：

严格模式与宽松模式

服务器使用两种验证模型：

from _validators import PermissiveModel, StrictModel

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/04af6ce3ff58fb74017a715ad66d987d4bef45c8/servers/perplexity/_models.py)

环境配置问题

.env 文件配置

服务器支持通过 .env 文件加载本地配置：

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/04af6ce3ff58fb74017a715ad66d987d4bef45c8/servers/atlassian-confluence/server.py)

标准 .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 环境变量控制日志详细程度：

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/04af6ce3ff58fb74017a715ad66d987d4bef45c8/servers/perplexity/server.py)

运行时异常

依赖缺失

服务器依赖以下核心库：

服务器版本不兼容

检查服务器版本兼容性：

{
  "$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/04af6ce3ff58fb74017a715ad66d987d4bef45c8/servers/e2b/server.json)

调试流程图

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]

常用诊断命令

验证服务器配置

# 检查 Python 版本
python3 --version

# 验证依赖安装
pip list | grep -E "fastmcp|httpx|pydantic"

# 测试服务器启动
python3 servers/perplexity/server.py --help

检查环境变量

# 列出所有相关环境变量
env | grep -E "API_KEY|BASE_URL|LOG_LEVEL|HTTPX"

# 加载 .env 文件并检查
source .env && echo $PERPLEXITY_API_KEY

社区常见问题

根据社区讨论，用户在使用 MCP 服务器时常遇到以下问题：

1. 上下文膨胀问题：用户反馈使用 MEMORY.md 等文件导致上下文过大。本项目的轻量级 MCP 服务器可以帮助减少上下文负担。

1. 服务器管理复杂性：用户需要一个 GUI 工具来管理多个 MCP 服务器。本项目的 registry 提供了标准化的服务器配置格式。

相关文档

• MCP 服务器列表
• 快速入门指南
• 认证配置
• 服务器开发

项目概述

mcparmory/registry 是一个集中管理 MCP 服务器的开源项目，每个服务器都是一个独立的 PyPI 包，可以独立安装和运行。项目采用标准化的服务器定义格式，确保所有服务器都能通过统一的接口进行调用和管理。

根据 README.md 的说明，该注册表涵盖了多个服务类别，包括但不限于开发工具、通信平台、云服务、内容管理系统等。

贡献方式

添加新服务器

向注册表添加新服务器是最常见的贡献方式。每个服务器都需要遵循统一的项目结构：

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.json 文件，定义服务器的元数据和包信息：

{
  "$schema": "https://static.modelcontextprotocol.io/schemas/2025-12-11/server.schema.json",
  "name": "com.mcparmory/<server-name>",
  "description": "服务器功能描述",
  "version": "1.0.0",
  "repository": {
    "url": "https://github.com/mcparmory/registry",
    "source": "github"
  },
  "packages": [
    {
      "registryType": "pypi",
      "identifier": "mcparmory-<server-name>",
      "version": "1.0.0",
      "runtimeHint": "uvx",
      "transport": {
        "type": "stdio"
      }
    },
    {
      "registryType": "oci",
      "identifier": "ghcr.io/mcparmory/<server-name>:1.0.0",
      "runtimeHint": "docker",
      "transport": {
        "type": "stdio"
      }
    }
  ]
}

关键字段说明：

包注册要求

服务器需要同时提供 PyPI 和 OCI（容器镜像）两种分发方式：

PyPI 包配置：

• 包名格式：mcparmory-<server-name>
• 运行时提示：uvx
• 适合本地开发和测试

OCI 镜像配置：

• 镜像地址格式：ghcr.io/mcparmory/<server-name>:<version>
• 运行时提示：docker
• 适合生产环境部署

server.py 实现规范

基本框架

所有服务器主程序都遵循统一的实现模式，基于 FastMCP 框架构建：

#!/usr/bin/env python3
"""
<Server Name> MCP Server
Generated: <timestamp>
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 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)

环境变量配置：

工具定义模式

服务器通过装饰器模式定义可用的 MCP 工具：

@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 操作所需的认证方式：

OPERATION_AUTH = {
    "create_resource": [["ApiKey"]],
    "get_resource": [["ApiKey"]],
    "update_resource": [["ApiKey"], ["OAuth2"]],
    "delete_resource": [["ApiKey"]],
    "list_resources": [["ApiKey"], ["BearerAuth"]],
}

支持的认证类型包括：

数据模型规范 (_models.py)

模型基类

项目使用 Pydantic 定义请求和响应模型，提供两种验证模式：

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__ 列表，明确导出所有公共模型：

__all__ = [
    "CreateResourceRequest",
    "CreateResourceResponse",
    "ListResourcesRequest",
    "ListResourcesResponse",
    "ResourceModel",
]

提交规范

Pull Request 检查清单

在提交 PR 之前，请确保完成以下检查：

1. 代码结构检查

• [ ] 遵循服务器目录结构规范
• [ ] 包含所有必需文件（server.json, server.py, _models.py, _auth.py）
• [ ] 所有 Python 文件包含正确的 shebang 和文档字符串

1. 配置文件检查

• [ ] server.json 符合 JSON Schema 规范
• [ ] 版本号遵循语义化版本（SemVer）
• [ ] 包含 PyPI 和 OCI 两种包定义

1. 代码质量检查

• [ ] 所有工具函数包含完整的类型注解
• [ ] 参数描述使用 Pydantic Field 的 description
• [ ] 错误处理覆盖所有可能的异常情况
• [ ] 日志记录使用标准 logging 模块

1. 认证配置检查

• [ ] _auth.py 正确定义所有操作的认证方式
• [ ] 支持多种认证方式的操作已正确映射

提交信息规范

使用清晰明了的提交信息：

feat: 添加 Perplexity MCP 服务器支持
fix: 修复 Google Analytics 连接池泄漏问题
docs: 更新 README.md 服务器列表
refactor: 重构认证模块支持多认证方式

服务器分类参考

当前注册表涵盖以下服务类别，可作为新增服务器的参考：

常见问题

Q: 如何测试新添加的服务器？

A: 使用 uvx 直接运行服务器进行本地测试：

uvx mcparmory-<server-name>

Q: 是否支持自定义 BASE_URL？

A: 是的，所有服务器都支持通过环境变量自定义 API 端点：

export BASE_URL="https://custom-api.example.com"

Q: 如何处理需要 OAuth2 认证的 API？

A: 在 _auth.py 中定义 OAuth2 认证方式，并在 server.py 中实现完整的授权流程。参考现有服务器的 OAuth2 实现模式。

相关资源

• 官方 MCP 协议文档
• FastMCP 框架文档
• MCP Blacksmith 代码生成器
• PyPI 包发布指南

Pitfall Log / 踩坑日志

项目：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