# https://github.com/Data-Everything/MCP-Platform 项目说明书

生成时间：2026-06-14 03:20:57 UTC

## 目录

- [Platform Overview and Migration from MCP Server Templates](#page-1)
- [Deployment Architecture, Backends and Infrastructure](#page-2)
- [Templates, Template Development and Database Integrations](#page-3)
- [CLI, Interactive Shell, Python Client and Tool Discovery](#page-4)

<a id='page-1'></a>

## Platform Overview and Migration from MCP Server Templates

### 相关页面

相关主题：[Deployment Architecture, Backends and Infrastructure](#page-2), [Templates, Template Development and Database Integrations](#page-3)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [README.md](https://github.com/Data-Everything/MCP-Platform/blob/main/README.md)
- [mcp_platform/template/utils/__init__.py](https://github.com/Data-Everything/MCP-Platform/blob/main/mcp_platform/template/utils/__init__.py)
- [mcp_platform/template/utils/creation.py](https://github.com/Data-Everything/MCP-Platform/blob/main/mcp_platform/template/utils/creation.py)
- [mcp_platform/template/templates/demo/README.md](https://github.com/Data-Everything/MCP-Platform/blob/main/mcp_platform/template/templates/demo/README.md)
- [mcp_platform/template/templates/trino/README.md](https://github.com/Data-Everything/MCP-Platform/blob/main/mcp_platform/template/templates/trino/README.md)
- [mcp_platform/template/templates/gitlab/README.md](https://github.com/Data-Everything/MCP-Platform/blob/main/mcp_platform/template/templates/gitlab/README.md)
- [mcp_platform/template/templates/zendesk/README.md](https://github.com/Data-Everything/MCP-Platform/blob/main/mcp_platform/template/templates/zendesk/README.md)
- [mcp_platform/cli/cli.py](https://github.com/Data-Everything/MCP-Platform/blob/main/mcp_platform/cli/cli.py)
- [mcp_platform/cli/interactive_cli.py](https://github.com/Data-Everything/MCP-Platform/blob/main/mcp_platform/cli/interactive_cli.py)
- [mcp_platform/client/client.py](https://github.com/Data-Everything/MCP-Platform/blob/main/mcp_platform/client/client.py)
</details>

# Platform Overview and Migration from MCP Server Templates

## 项目定位与核心价值

MCP Platform 是面向生产环境的 Model Context Protocol（MCP）服务器部署平台，定位是让 AI 开发者无需关心底层容器编排与基础设施，即可"零配置"部署可投产的 MCP 服务器。平台将 Docker 容器、CLI 工具、模板缓存与配置管理整合为统一交付物，重点放在 AI 集成而非基础设施搭建 资料来源：[README.md:1-15]()。

相较于传统 MCP 部署方式，平台提供以下能力：

| 能力 | 说明 |
| --- | --- |
| 一键部署 | 通过预构建模板与 `mcpp deploy <template>` 命令完成部署 |
| 智能工具发现 | 自动识别并展示服务器暴露的工具列表 |
| 模板缓存 | 内置 6 小时模板缓存，自动失效以加速列表与发现操作 |
| 多后端管理 | 通过 `MultiBackendManager` 统一管理本地与远端后端的部署状态 |
| 灵活配置 | 支持 JSON、YAML、环境变量与 CLI 选项四种配置入口 |

资料来源：[README.md:31-46]() 与 [mcp_platform/client/client.py:18-35]()。

## 平台架构概览

平台整体由 CLI 入口、客户端 API、模板发现层与多后端管理器组成。用户既可以通过 `mcpp` 命令行工具交互，也可以通过 `MCPClient` 进行编程调用，二者底层共享 `TemplateManager`、`DeploymentManager`、`ToolCaller` 等核心模块 资料来源：[mcp_platform/client/client.py:25-50]()。

```mermaid
flowchart LR
    A[CLI / Interactive CLI] --> B[MCPClient]
    C[Python API 调用方] --> B
    B --> D[TemplateManager]
    B --> E[DeploymentManager]
    B --> F[ToolManager / ToolCaller]
    D --> G[TemplateDiscovery]
    G --> H[mcp_platform/template/templates/*]
    E --> I[MultiBackendManager]
    I --> J[Docker / Kubernetes 等后端]
```

模板发现通过 `TemplateDiscovery` 在 `mcp_platform/template/templates/` 目录下进行动态扫描；该模块同时被 `TemplateCreator`（模板脚手架生成器）使用，用于克隆一份与 PostgreSQL、Trino 等既有模板结构一致的骨架 资料来源：[mcp_platform/template/utils/__init__.py:8-15]() 与 [mcp_platform/template/utils/creation.py:40-80]()。

## 从 MCP Server Templates 迁移到 MCP Platform

旧的 `mcp-templates` 旧包已转入维护模式，仅接收安全更新至 2025 年；新项目更名为 `mcp-platform`，迁移成本极低 资料来源：[README.md:78-90]()。

迁移包含以下步骤：

1. 卸载旧包并安装新包：

   ```bash
   pip uninstall mcp-templates
   pip install mcp-platform
   ```

2. 命令保持向后兼容：`mcpp deploy demo` 在新旧版本下完全一致，Docker 镜像与配置文件无需修改 资料来源：[README.md:95-105]()。

3. 更新文档书签与版本号：`mcp-platform` 的版本从 1.1.0（Slack 与 BigQuery 模板发布）一路演进到 1.3.1（Kubeconfig 环境变量配置），新版本会持续引入新模板与网关改进 资料来源：[README.md:107-140]()。

迁移过程中需要注意两类一致性：

- **文档一致性**：每个模板自带 `docs` 子目录，部分模板（如 BigQuery）曾出现过工具调用说明错误，社区已要求统一使用 `mcp_platform` 客户端或 CLI 调用工具 资料来源：[README.md:118-130]()（参见 [Issue #27](https://github.com/Data-Everything/MCP-Platform/issues/27)）。
- **CI 一致性**：项目的 `build-docs` 工作流曾因浅克隆仓库导致 `setuptools_scm` 报错，需关注文档构建状态 资料来源：[Issue #43](https://github.com/Data-Everything/MCP-Platform/issues/43)。

## 社区驱动的模板演进

平台模板覆盖演示、文件系统、代码托管（GitHub/GitLab）、数据仓库（Trino/PostgreSQL/BigQuery）、工单系统（Zendesk）等场景。新增模板通常遵循"复用现有结构 → 适配上游实现 → 通过 `mcpp create` 生成脚手架"的工作流 资料来源：[mcp_platform/template/utils/creation.py:30-60]()。

几个值得关注的演进方向：

- **Trino 模板**：基于 FastMCP 与 SQLAlchemy，默认只读并限制 1000 行结果，支持 HTTP/stdio 双传输 资料来源：[mcp_platform/template/templates/trino/README.md:1-25]()。
- **GitLab 模板**：覆盖 66+ 工具，提供只读模式与可选特性开关，可对接自托管 GitLab 资料来源：[mcp_platform/template/templates/gitlab/README.md:1-30]()。
- **Zendesk 模板**：内置工单、用户、知识库与分析能力，使用 FastMCP 与异步 I/O 实现 资料来源：[mcp_platform/template/templates/zendesk/README.md:1-25]()。
- **Demo 模板**：作为最小可运行示例，帮助用户理解 `server.py` 模块化结构与 CLI 部署 资料来源：[mcp_platform/template/templates/demo/README.md:1-30]()。

社区已就 Snowflake（[#24](https://github.com/Data-Everything/MCP-Platform/issues/24)、[#41](https://github.com/Data-Everything/MCP-Platform/issues/41)）、Elasticsearch（[#33](https://github.com/Data-Everything/MCP-Platform/issues/33)）、BigQuery（[#20](https://github.com/Data-Everything/MCP-Platform/issues/20)）等模板提出复制请求，均建议以现有 PostgreSQL 模板为蓝本。

## See Also

- [Template Creation Utilities](Template-Creation-Utilities.md)
- [Template Discovery and Registry](Template-Discovery.md)
- [CLI Reference](CLI-Reference.md)
- [Interactive CLI Guide](Interactive-CLI.md)
- [MCPClient Programmatic API](MCP-Client-API.md)
- [Available Templates Catalog](Available-Templates.md)

---

<a id='page-2'></a>

## Deployment Architecture, Backends and Infrastructure

### 相关页面

相关主题：[Platform Overview and Migration from MCP Server Templates](#page-1), [CLI, Interactive Shell, Python Client and Tool Discovery](#page-4)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [mcp_platform/core/deployment_manager.py](https://github.com/Data-Everything/MCP-Platform/blob/main/mcp_platform/core/deployment_manager.py)
- [mcp_platform/core/multi_backend_manager.py](https://github.com/Data-Everything/MCP-Platform/blob/main/mcp_platform/core/multi_backend_manager.py)
- [mcp_platform/backends/base.py](https://github.com/Data-Everything/MCP-Platform/blob/main/mcp_platform/backends/base.py)
- [mcp_platform/backends/docker.py](https://github.com/Data-Everything/MCP-Platform/blob/main/mcp_platform/backends/docker.py)
- [mcp_platform/backends/kubernetes.py](https://github.com/Data-Everything/MCP-Platform/blob/main/mcp_platform/backends/kubernetes.py)
- [mcp_platform/backends/mock.py](https://github.com/Data-Everything/MCP-Platform/blob/main/mcp_platform/backends/mock.py)
- [mcp_platform/cli/cli.py](https://github.com/Data-Everything/MCP-Platform/blob/main/mcp_platform/cli/cli.py)
- [mcp_platform/cli/interactive_cli.py](https://github.com/Data-Everything/MCP-Platform/blob/main/mcp_platform/cli/interactive_cli.py)
- [README.md](https://github.com/Data-Everything/MCP-Platform/blob/main/README.md)
- [mcp_platform/template/templates/demo/README.md](https://github.com/Data-Everything/MCP-Platform/blob/main/mcp_platform/template/templates/demo/README.md)
- [mcp_platform/template/templates/slack/README.md](https://github.com/Data-Everything/MCP-Platform/blob/main/mcp_platform/template/templates/slack/README.md)
- [mcp_platform/template/templates/gitlab/README.md](https://github.com/Data-Everything/MCP-Platform/blob/main/mcp_platform/template/templates/gitlab/README.md)
</details>

# 部署架构、后端与基础设施

## 概述

MCP-Platform 的部署层负责将一个或多个 MCP 模板（template）落地为可运行的 MCP 服务实例。平台对外以 `mcpp` 命令行提供零配置部署体验，对内则通过客户端（`MCPClient`）和后端管理器（`MultiBackendManager`）对接多种容器/编排运行时，从而把"模板"与"基础设施"解耦。项目自述文件强调："Zero-configuration deployment of production-ready MCP servers with Docker containers, comprehensive CLI tools, and intelligent caching" 资料来源：[README.md:1-20](https://github.com/Data-Everything/MCP-Platform/blob/main/README.md)。这一层既是用户接触最频繁的入口，也是项目从 `mcp-templates` 升级到 `mcp-platform` 后的核心改动点之一（Release 1.3.0 的"Gateway improvement"与 Release 1.3.1 的 "Kubeconfig environment variable config" 均直接关联此层）。

## 架构总览

部署架构自顶向下分为四层：**CLI/交互层**、**客户端层**、**多后端管理层**和**具体后端实现层**。CLI 将用户命令转译为客户端调用，客户端再委托给后端管理器，最后由具体后端（Docker / Kubernetes / Mock）真正启动容器或 Pod。架构图如下：

```mermaid
graph TB
    User[用户/开发者] --> CLI[mcpp CLI]
    CLI --> ICLI[Interactive CLI]
    CLI --> Client[MCPClient]
    ICLI --> Client
    Client --> MBM[MultiBackendManager]
    MBM --> Docker[Docker Backend]
    MBM --> K8s[Kubernetes Backend]
    MBM --> Mock[Mock Backend]
    Docker --> Containers[MCP Server Containers]
    K8s --> Pods[MCP Server Pods]
    MBM --> Config[ConfigProcessor]
    MBM --> Cache[CacheManager]
    MBM --> RF[ResponseFormatter]
```

`list` 命令的输出会显式呈现 "Available MCP Server Templates (All Backends)"，并可通过 `--backend` 限定到单个后端，或通过 `--unified` 切换为单表视图 资料来源：[mcp_platform/cli/cli.py:list()](https://github.com/Data-Everything/MCP-Platform/blob/main/mcp_platform/cli/cli.py)。这表明后端切换是**一等公民能力**，而非事后补丁。

## 核心组件与职责

### 部署管理器（DeploymentManager）

`DeploymentManager` 是单个后端上执行"部署-查询-停止-清理"生命周期的主控制器。它接收模板 ID、配置覆盖和后端实例，统一处理端口映射、环境变量注入、健康检查和日志采集等横切关注点。其契约由 `mcp_platform/backends/base.py` 中的抽象基类定义，所有具体后端必须实现 `deploy / list_deployments / stop / cleanup` 等方法 资料来源：[mcp_platform/backends/base.py](https://github.com/Data-Everything/MCP-Platform/blob/main/mcp_platform/backends/base.py)。

### 多后端管理器（MultiBackendManager）

当用户在一次操作中需要同时观察 Docker 与 Kubernetes 上的运行实例时，`MultiBackendManager` 负责聚合多后端结果。它在 CLI 中通过 `client._multi_manager.get_available_backends()` 暴露能力查询接口 资料来源：[mcp_platform/cli/cli.py:list()](https://github.com/Data-Everything/MCP-Platform/blob/main/mcp_platform/cli/cli.py)。对于不支持的后端，平台会跳过而不是报错，从而保证 `list` 在混合环境中仍可使用。

### 后端实现

| 后端 | 主要用途 | 关键特性 |
| --- | --- | --- |
| Docker（`docker.py`） | 本地与单主机部署，开箱即用 | 镜像拉取、容器生命周期、`docker network create mcp-platform` 命名网络 资料来源：[mcp_platform/template/templates/demo/README.md:Troubleshooting](https://github.com/Data-Everything/MCP-Platform/blob/main/mcp_platform/template/templates/demo/README.md) |
| Kubernetes（`kubernetes.py`） | 集群化、企业级部署 | 通过 Kubeconfig 环境变量注入凭据 资料来源：[Release 1.3.1](https://github.com/Data-Everything/MCP-Platform/releases/tag/release-pypi-1.3.1) |
| Mock（`mock.py`） | 测试与 CI 流水线 | 内存中模拟部署状态，可用于 Issue #43 中 build-docs 工作流的离线验证 |

## 客户端编排与多后端支持

`MCPClient` 是 CLI 与后端之间的稳定边界。它在构造时接受 `backend_type` 参数，CLI 既允许通过 `--backend` 单次指定，也通过 `cli_state["backend_type"]` 维护会话级默认值 资料来源：[mcp_platform/cli/cli.py:list()](https://github.com/Data-Everything/MCP-Platform/blob/main/mcp_platform/cli/cli.py)。客户端的 `list_templates(include_deployed_status=True, all_backends=not backend)` 会把"模板目录扫描"与"运行态采集"合并为一次调用，从而在 `mcpp list` 一张表里同时展示"模板元数据 + 部署状态" 资料来源：[mcp_platform/cli/cli.py:list()](https://github.com/Data-Everything/MCP-Platform/blob/main/mcp_platform/cli/cli.py)。

交互式 CLI 在历史上曾支持"先 `select demo` 再隐式注入模板"的快捷模式，但该逻辑已被移除："The previous implementation supported selecting a template for the session and auto-injecting it into commands; that feature has been removed to simplify the interactive CLI" 资料来源：[mcp_platform/cli/interactive_cli.py:顶部注释](https://github.com/Data-Everything/MCP-Platform/blob/main/mcp_platform/cli/interactive_cli.py)。此改动降低了"忘记切回全局上下文"导致的误操作风险，也使多后端场景下命令语义保持一致。

## 部署流程与典型用法

一次典型部署的流程为：**选择模板 → 注入配置 → 选定后端 → 拉起实例 → 采集日志/状态**。平台同时提供 Docker 直跑与 CLI 托管两种入口。以 Slack 模板为例，二者等价 资料来源：[mcp_platform/template/templates/slack/README.md:Quick Start](https://github.com/Data-Everything/MCP-Platform/blob/main/mcp_platform/template/templates/slack/README.md)：

```bash
# Docker 直跑
docker run -i --rm \
  -e SLACK_MCP_XOXP_TOKEN=xoxp-your-token \
  ghcr.io/korotovsky/slack-mcp-server:v1.1.24 \
  mcp-server --transport stdio

# MCP Platform 托管
python -m mcp_platform deploy slack \
  --config slack_mcp_xoxp_token=xoxp-your-token
```

对于自托管实例（GitLab Enterprise 等），模板会要求额外环境变量，如 `GITLAB_API_URL` 与 `HTTP_PROXY`，并支持 read-only 模式（`GITLAB_READ_ONLY_MODE=true`）以限制可执行工具 资料来源：[mcp_platform/template/templates/gitlab/README.md:Self-Hosted GitLab](https://github.com/Data-Everything/MCP-Platform/blob/main/mcp_platform/template/templates/gitlab/README.md)。配置层（`ConfigProcessor`）会自动把 `"true"/"123"/'["a","b"]'` 等字符串转换为对应的 `bool / int / JSON` 类型，从而让 CLI 参数、JSON/YAML 文件与环境变量之间可互换 资料来源：[mcp_platform/template/templates/demo/README.md:Configuration](https://github.com/Data-Everything/MCP-Platform/blob/main/mcp_platform/template/templates/demo/README.md)。

## 常见失败模式

1. **端口冲突**：默认 HTTP 端口 8080 被占用，需通过 `--port` 覆盖；Demo 模板建议改为 7072 资料来源：[mcp_platform/template/templates/demo/README.md:Troubleshooting](https://github.com/Data-Everything/MCP-Platform/blob/main/mcp_platform/template/templates/demo/README.md)。
2. **Docker 网络未创建**：跨容器通信前需要 `docker network create mcp-platform` 资料来源：[mcp_platform/template/templates/demo/README.md:Troubleshooting](https://github.com/Data-Everything/MCP-Platform/blob/main/mcp_platform/template/templates/demo/README.md)。
3. **CI 工作流与浅克隆不兼容**：build-docs 流程在浅克隆仓库下会触发 `setuptools_scm` 警告甚至失败 资料来源：[Issue #43](https://github.com/Data-Everything/MCP-Platform/issues/43)。
4. **模板文档与 CLI 实际调用方式不一致**：历史上 BigQuery 模板文档曾给出"API 调用"示例，而非 `mcpp`/客户端调用方式 资料来源：[Issue #27](https://github.com/Data-Everything/MCP-Platform/issues/27)，且各模板文档风格分散 资料来源：[Issue #28](https://github.com/Data-Everything/MCP-Platform/issues/28)。排查时优先以 `mcpp tools <template>` 与本仓库 README 为准。

## See Also

- [Template Discovery & Authoring](template-discovery.md) — 模板目录扫描与 `TemplateCreator` 工具
- [Configuration System](configuration-system.md) — `ConfigProcessor` 的类型转换与覆盖语义
- [CLI Reference](cli-reference.md) — `mcpp` 子命令的完整列表
- [MCP Protocol & Tool Invocation](mcp-protocol.md) — 部署后的工具发现与调用

---

<a id='page-3'></a>

## Templates, Template Development and Database Integrations

### 相关页面

相关主题：[Deployment Architecture, Backends and Infrastructure](#page-2), [CLI, Interactive Shell, Python Client and Tool Discovery](#page-4)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [mcp_platform/template/utils/__init__.py](https://github.com/Data-Everything/MCP-Platform/blob/main/mcp_platform/template/utils/__init__.py)
- [mcp_platform/template/utils/creation.py](https://github.com/Data-Everything/MCP-Platform/blob/main/mcp_platform/template/utils/creation.py)
- [mcp_platform/template/templates/demo/README.md](https://github.com/Data-Everything/MCP-Platform/blob/main/mcp_platform/template/templates/demo/README.md)
- [mcp_platform/template/templates/gitlab/README.md](https://github.com/Data-Everything/MCP-Platform/blob/main/mcp_platform/template/templates/gitlab/README.md)
- [mcp_platform/template/templates/github/README.md](https://github.com/Data-Everything/MCP-Platform/blob/main/mcp_platform/template/templates/github/README.md)
- [mcp_platform/template/templates/zendesk/README.md](https://github.com/Data-Everything/MCP-Platform/blob/main/mcp_platform/template/templates/zendesk/README.md)
- [mcp_platform/cli/interactive_cli.py](https://github.com/Data-Everything/MCP-Platform/blob/main/mcp_platform/cli/interactive_cli.py)
- [mcp_platform/client/client.py](https://github.com/Data-Everything/MCP-Platform/blob/main/mcp_platform/client/client.py)
- [README.md](https://github.com/Data-Everything/MCP-Platform/blob/main/README.md)
</details>

# 模板、模板开发与数据库集成

## 概述与定位

MCP-Platform 的**模板（Template）**是预打包、可一键部署的 Model Context Protocol 服务器单元。每个模板封装了一个具体的外部系统集成（如 GitHub、GitLab、Zendesk、Postgres、Trino、BigQuery 等），并提供统一的配置模型、Docker 镜像、工具清单与文档，使 LLM 客户端能够以零配置方式调用这些工具。

模板系统的入口由 `mcp_platform/template/utils/__init__.py` 暴露，主要对外提供两类能力：

- `TemplateDiscovery`：动态发现本地与已部署的模板。
- `TemplateCreator`：交互式或基于配置生成新模板脚手架。

资料来源：[mcp_platform/template/utils/__init__.py:1-18]()。

平台顶层通过 `MCPClient` 抽象访问这些能力，例如 `validate_template`、`search_templates`、`list_servers` 等方法都通过 `template_manager` 间接读取模板清单与元数据。资料来源：[mcp_platform/client/client.py:1-50]()。

## 模板架构

模板目录遵循统一的目录约定，每个子目录包含 `template.json`（元数据与配置模式）、`config.py`（运行时配置类）、`tools.py`（FastMCP 工具定义）、`server.py`（入口）、`Dockerfile` 与 `README.md`/`docs/`。

`demo` 模板的 README 描述了"四模块"分层结构：配置（`config.py`）、工具（`tools.py`）、服务（`server.py`）以及一个用于演示覆盖参数行为的辅助函数。该模块化设计使得各层可独立测试与替换。资料来源：[mcp_platform/template/templates/demo/README.md:1-40]()。

下面以 mermaid 图展示一个典型模板从发现到部署的流转：

```mermaid
flowchart LR
  A[本地 templates/<id>/] --> B[TemplateDiscovery 扫描]
  C[TemplateCreator 生成] --> A
  B --> D[template.json + config_schema]
  D --> E[MCPClient.validate_template]
  E --> F[mcpp deploy / interactive call]
  F --> G[Docker 容器化运行]
  G --> H[LLM 客户端调用工具]
```

模板元数据在 `template.json` 中声明：

| 字段 | 用途 | 示例（demo 模板） |
|---|---|---|
| `id` | 模板唯一标识 | `demo` |
| `name` | 模板显示名 | `Demo MCP Server` |
| `config_schema` | 配置属性与 `env_mapping` | `hello_from`, `log_level` |
| `tools` | 暴露给 LLM 的工具清单 | `say_hello`, `get_server_info` |
| `docker_image` | 容器镜像名 | `dataeverything/mcp-demo` |

资料来源：[mcp_platform/template/templates/demo/template.json:1-60]()（结合 README 中的"配置属性"段落）。

## 模板开发工作流

`TemplateCreator` 是新增模板的官方入口。它支持两种模式：

1. **交互式模式**：通过 Rich 终端提示依次收集 `template_id`、名称、描述、配置属性、工具清单，并要求最终确认；如目标目录已存在会询问是否覆盖。
2. **配置文件模式**：传入 `config_file` 后批量生成结构化输出。

资料来源：[mcp_platform/template/utils/creation.py:30-80]()。

`create_template_interactive` 在收集完元数据后，会依次生成：

- `config.py`：从 `mcp_platform/utils/config.py` 读取 demo 模板并按 `template_id` 替换类名（如 `postgres` → `PostgresServerConfig`）。
- `docs/index.md`：列出必填配置项与每个 `capability` 的示例与参数。
- `README.md`：包含 Quick Start、Docker 构建与运行命令、测试入口等段落。
- `Dockerfile`：标准容器化模板。

资料来源：[mcp_platform/template/utils/creation.py:80-200]()。

社区中已有多个通过复制现有模式新增数据库模板的请求，例如：

- Issue #36 请求按 `templates/trino/` 目录结构新增 Trino 模板，并复用上游 `mcp-trino` 实现（已在 v1.2.0 落地，参见 Release `release-pypi-1.2.0`）。
- Issue #24 / #41 提议复制 Postgres 模板创建 Snowflake 模板，覆盖 snowflake-connector-python 的全部认证机制。
- Issue #33 请求扩展官方 elasticsearch mcp server 为平台模板。

资料来源：社区 Issue 与 Release 记录。

> ⚠️ 文档一致性是社区重点关注的问题。Issue #28 指出 `mcp_platform/template/templates` 下各模板自带文档风格不一，Issue #27 指出 BigQuery 模板文档曾给出过错误的 API 调用说明（应使用 `mcpp` CLI 或 `MCPClient` 而非直接 HTTP）。开发新模板时请统一遵循 `TemplateCreator` 生成的目录与 README 骨架。

## 数据库集成模板

数据库集成是模板扩展最活跃的方向。当前已发布的相关模板及对应 issue 如下：

| 模板 | 状态 | 社区引用 |
|---|---|---|
| Postgres | 已发布（v1.3.0） | Release `release-pypi-1.3.0` |
| Trino | 已发布（v1.2.0 重写） | Issue #36，Release `release-pypi-1.2.0` |
| BigQuery | 已发布（v1.1.0，v1.2.0 修复） | Issue #20，Issue #27 |
| Snowflake | 计划中（基于 Postgres 模式复制） | Issue #24、#41 |
| Elasticsearch / OpenSearch | 已发布（v1.2.0 双引擎） | Issue #33，PR #34 |

对于数据库类模板，社区共识（参见 Issue #41）是将 Postgres 模板作为参考基线：相同的目录结构、`config_schema`、`env_mapping` 与工具抽象层，再叠加各自驱动/认证机制。例如 Postgres 模板的 `template.json` 暴露的连接参数会通过 `env_mapping` 映射到 `POSTGRES_HOST`、`POSTGRES_PORT`、`POSTGRES_USER`、`POSTGRES_PASSWORD`、`POSTGRES_DATABASE` 等环境变量；Trino 与 Snowflake 沿用相同模式，但分别扩展 Trino 的 catalog/user 认证与 Snowflake 的多种认证机制（密码、Key-Pair、OAuth、External Browser）。资料来源：[mcp_platform/template/templates/postgres/template.json:1-60]()（参考），Issue #41。

部署后，调用通过统一入口完成。交互式 CLI 文档示例：

```
call postgres execute_query '{"sql": "SELECT 1"}'
```

资料来源：[mcp_platform/cli/interactive_cli.py:1-80]()。

## 常见失败模式

- **文档构建失败**：Issue #43 报告 GitHub Action `build-docs.py` 在浅克隆环境下因 `setuptools_scm` 警告导致流水线失败，建议在 CI 中显式 fetch 历史或固定版本标签。
- **配置覆盖类型转换**：模板支持 CLI / JSON / YAML 覆盖参数，`true/false` 自动转为布尔、数字自动转为 int/float、字符串 JSON 自动解析为对象或数组；非合规输入会被 `ConfigProcessor` 拒绝。
- **端口冲突**：本地调试时若 8000/7072 端口被占用，需通过 `--port` 显式指定。资料来源：[mcp_platform/template/templates/demo/README.md:1-60]()。
- **文档不一致**：避免手工编辑各模板 README，统一通过 `TemplateCreator` 重新生成以减少风格漂移。资料来源：Issue #28。

## See Also

- [Templates, Template Discovery & Configuration](Templates-Discovery-and-Configuration.md)
- [CLI 与交互式调用](CLI-and-Interactive-Usage.md)
- [MCPClient API 参考](MCPClient-API.md)

---

<a id='page-4'></a>

## CLI, Interactive Shell, Python Client and Tool Discovery

### 相关页面

相关主题：[Deployment Architecture, Backends and Infrastructure](#page-2), [Templates, Template Development and Database Integrations](#page-3)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [mcp_platform/cli/cli.py](https://github.com/Data-Everything/MCP-Platform/blob/main/mcp_platform/cli/cli.py)
- [mcp_platform/cli/interactive_cli.py](https://github.com/Data-Everything/MCP-Platform/blob/main/mcp_platform/cli/interactive_cli.py)
- [mcp_platform/cli/__init__.py](https://github.com/Data-Everything/MCP-Platform/blob/main/mcp_platform/cli/__init__.py)
- [mcp_platform/client/client.py](https://github.com/Data-Everything/MCP-Platform/blob/main/mcp_platform/client/client.py)
- [mcp_platform/template/utils/creation.py](https://github.com/Data-Everything/MCP-Platform/blob/main/mcp_platform/template/utils/creation.py)
- [mcp_platform/template/utils/__init__.py](https://github.com/Data-Everything/MCP-Platform/blob/main/mcp_platform/template/utils/__init__.py)
- [mcp_platform/template/templates/demo/README.md](https://github.com/Data-Everything/MCP-Platform/blob/main/mcp_platform/template/templates/demo/README.md)
- [mcp_platform/template/templates/gitlab/README.md](https://github.com/Data-Everything/MCP-Platform/blob/main/mcp_platform/template/templates/gitlab/README.md)
- [mcp_platform/template/templates/github/README.md](https://github.com/Data-Everything/MCP-Platform/blob/main/mcp_platform/template/templates/github/README.md)
</details>

# CLI、交互式 Shell、Python 客户端与工具发现

## 1. 概述与定位

MCP-Platform 提供了三层面向不同用户群体的访问入口：基于 Typer 的命令行工具（`mcpp`）、带历史记录与补全功能的交互式 Shell，以及面向程序员的 Python API（`MCPClient`）。三者共享同一套核心模块（`mcp_platform.core`）和模板发现机制（`TemplateDiscovery`），以保证命令、交互会话和 Python 调用在行为与输出上保持一致。

资料来源：[mcp_platform/client/client.py:1-40]()、[mcp_platform/cli/cli.py:1-30]()

## 2. 命令行接口（CLI）

### 2.1 入口与全局选项

`mcp_platform/cli/cli.py` 中通过 Typer 框架注册 `app`，并自定义了 `AliasGroup`，允许使用逗号或斜杠作为命令别名分隔符（如 `list,deploy`）。

资料来源：[mcp_platform/cli/cli.py:33-49]()

全局回调支持两个常用选项：

| 选项 | 说明 | 默认值 |
|------|------|--------|
| `--verbose, -v` | 启用详细输出 | `False` |
| `--backend` | 指定后端类型（如 docker、kubernetes） | `docker` |

资料来源：[mcp_platform/cli/cli.py:99-117]()

### 2.2 常用命令

- `config <template>`：读取并展示某个模板的可配置属性，从 `config_schema.properties` 中提取参数列表。
- `deploy`、`stop`、`status`、`logs`、`list`、`list-tools`：分别负责部署、停止、状态查看、日志获取、模板与工具列举。
- 通过 `__init__.py` 统一导出，避免在不同入口出现循环引用。

资料来源：[mcp_platform/cli/cli.py:118-150]()、[mcp_platform/cli/__init__.py:1-20]()

> 社区上下文：issue [#27](https://github.com/Data-Everything/MCP-Platform/issues/27) 反馈部分模板文档错误地描述了“通过 API 调用工具”的方式，正确做法应使用 `mcpp` CLI 或 `MCPClient` 调用工具调用机制。

## 3. 交互式 Shell

`mcp_platform/cli/interactive_cli.py` 使用 Typer 与 `readline`（如可用）实现 REPL 风格会话，提供命令历史（上下方向键）与 Tab 补全。

### 3.1 已注册命令

会话启动时声明的核心命令包括：`help`、`templates`、`tools`、`call`、`deploy`、`configure`、`logs`、`stop` 等，与 CLI 子命令保持一致，但省略了显式后端参数。

资料来源：[mcp_platform/cli/interactive_cli.py:60-80]()

### 3.2 显式模板参数策略

代码注释明确说明：旧的“会话级模板选择/隐式注入”功能已被移除，所有命令必须在调用时显式传入模板名称，并在缺失时返回清晰错误。这样做的目的是降低误用概率，与 issue [#28](https://github.com/Data-Everything/MCP-Platform/issues/28) 中提到的“模板文档不一致”问题相呼应——通过强制显式参数减少歧义。

资料来源：[mcp_platform/cli/interactive_cli.py:42-55]()

### 3.3 日志命令委托

`logs` 子命令通过 `from mcp_platform.cli import logs as cli_logs` 直接委托主 CLI 函数，避免逻辑重复。

资料来源：[mcp_platform/cli/interactive_cli.py:111-126]()

## 4. Python 客户端（MCPClient）

### 4.1 类职责

`MCPClient`（`mcp_platform/client/client.py`）是对核心模块的高层封装，统一了以下能力：

- `list_templates()` / `get_template_info()` / `validate_template()` / `search_templates()`：模板元数据访问。
- `list_servers()` / `start_server()` / `stop_server()`：部署生命周期管理。
- `list_tools()` / `call_tool()`：工具发现与调用。

其内部聚合了 `DeploymentManager`、`MCPConnection`、`TemplateManager`、`ToolCaller`、`ToolManager` 等组件。

资料来源：[mcp_platform/client/client.py:66-100]()

### 4.2 典型用法示例

代码顶部文档给出了 asyncio 风格的调用流程：列出模板 → 启动服务 → 列举工具 → 调用工具 → 列出运行中的服务，演示了 Python API 的端到端工作流。

资料来源：[mcp_platform/client/client.py:13-38]()

## 5. 工具发现机制

### 5.1 模板级元数据

每个模板目录下均包含 `template.json`（包含 `capabilities` 字段）、`config.py`、`server.py`、`tools.py` 等文件，模板级 README（如 GitHub、GitLab、Zendesk、Demo）详细列举了可暴露的工具名称，例如：

- GitHub 模板：77+ 工具，覆盖仓库、分支、Issue、PR、操作等。
- GitLab 模板：66+ 工具，覆盖仓库、Issue、MR、Pipeline、Wiki、里程碑，并支持 `USE_GITLAB_WIKI`、`USE_MILESTONE`、`USE_PIPELINE` 等特性开关。

资料来源：[mcp_platform/template/templates/github/README.md:1-30]()、[mcp_platform/template/templates/gitlab/README.md:1-60]()

### 5.2 模板创建与文档生成

`TemplateCreator`（`mcp_platform/template/utils/creation.py`）会根据用户输入的能力（`capabilities`）生成 `docs/index.md`，包含：

- 配置项列表（来自 `config_schema.properties`，标注必填项）。
- 每个能力（Capability）的示例与参数类型。
- API 参考章节，自动从能力名派生出工具名（`lower().replace(' ', '_')`）。

这保证了文档与实际工具清单的同步，缓解 issue [#28](https://github.com/Data-Everything/MCP-Platform/issues/28) 所述的“模板文档不一致”问题。

资料来源：[mcp_platform/template/utils/creation.py:130-210]()、[mcp_platform/template/utils/__init__.py:1-14]()

### 5.3 数据流概览

```mermaid
flowchart LR
    A[用户] --> B[mcpp CLI]
    A --> C[Interactive Shell]
    A --> D[Python MCPClient]
    B --> E[TemplateDiscovery]
    C --> E
    D --> E
    E --> F[模板元数据 + 工具清单]
    F --> G[部署后端<br/>Docker / K8s]
    G --> H[MCP Server 进程]
    H --> I[工具调用结果]
    I --> B
    I --> C
    I --> D
```

## 6. 常见问题与排障

| 现象 | 根因 | 解决方式 |
|------|------|----------|
| CLI 文档显示“通过 API 调用”而非 CLI | 模板文档未统一（issue #27） | 使用 `mcpp call <template> <tool> '{...}'` 或 `MCPClient.call_tool()` |
| 交互式 Shell 报错“未指定模板” | 旧版本隐式选择被移除 | 显式传入 `template` 参数 |
| 文档与工具清单不一致 | 模板创建未走 `TemplateCreator` | 重新生成 `docs/index.md`，核对 `config_schema` |
| `build-docs` 工作流失败 | 浅克隆导致 setuptools_scm 告警（issue #43） | 关注上游修复或使用完整克隆 |

资料来源：[mcp_platform/cli/interactive_cli.py:42-55]()、[mcp_platform/template/utils/creation.py:130-180]()

## 7. 参见

- 模板清单与新增请求：Snowflake（[#24](https://github.com/Data-Everything/MCP-Platform/issues/24)）、Trino（[#36](https://github.com/Data-Everything/MCP-Platform/issues/36)）、Elasticsearch（[#33](https://github.com/Data-Everything/MCP-Platform/issues/33)）。
- 后端与部署：参考 `mcp_platform/backends` 与 `mcp_platform.core.deployment_manager`（本文未展开）。
- 版本发布记录：1.3.1（Kubeconfig 环境变量）、1.3.0（Postgres 模板）、1.2.0（Trino、Elasticsearch 改进）。

---

<!-- evidence_pipeline_checked: true -->
<!-- evidence_injected: true -->

---

## Doramagic 踩坑日志

项目：Data-Everything/MCP-Platform

摘要：发现 14 个潜在踩坑项，其中 0 个为 high/blocking；最高优先级：能力坑 - 能力判断依赖假设。

## 1. 能力坑 · 能力判断依赖假设

- 严重度：medium
- 证据强度：source_linked
- 发现：README/documentation is current enough for a first validation pass.
- 对用户的影响：假设不成立时，用户拿不到承诺的能力。
- 证据：capability.assumptions | https://github.com/Data-Everything/MCP-Platform | README/documentation is current enough for a first validation pass.

## 2. 维护坑 · 维护活跃度未知

- 严重度：medium
- 证据强度：source_linked
- 发现：未记录 last_activity_observed。
- 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。
- 证据：evidence.maintainer_signals | https://github.com/Data-Everything/MCP-Platform | last_activity_observed missing

- 严重度：medium
- 证据强度：source_linked
- 发现：no_demo
- 证据：downstream_validation.risk_items | https://github.com/Data-Everything/MCP-Platform | no_demo; severity=medium

## 4. 安全/权限坑 · 存在评分风险

- 严重度：medium
- 证据强度：source_linked
- 发现：no_demo
- 对用户的影响：风险会影响是否适合普通用户安装。
- 证据：risks.scoring_risks | https://github.com/Data-Everything/MCP-Platform | no_demo; severity=medium

## 5. 安全/权限坑 · 来源证据：[BUG] Bigquery template docs has wrong information about how to call tools

- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：[BUG] Bigquery template docs has wrong information about how to call tools
- 对用户的影响：可能影响授权、密钥配置或安全边界。
- 证据：community_evidence:github | https://github.com/Data-Everything/MCP-Platform/issues/27 | 来源讨论提到 docker 相关条件，需在安装/试用前复核。

## 6. 安全/权限坑 · 来源证据：[BUG] Github workflow build-docs failing

- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：[BUG] Github workflow build-docs failing
- 对用户的影响：可能影响授权、密钥配置或安全边界。
- 证据：community_evidence:github | https://github.com/Data-Everything/MCP-Platform/issues/43 | 来源讨论提到 python 相关条件，需在安装/试用前复核。

## 7. 安全/权限坑 · 来源证据：[BUG] Templates specific documentation inconsistent

- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：[BUG] Templates specific documentation inconsistent
- 对用户的影响：可能影响授权、密钥配置或安全边界。
- 证据：community_evidence:github | https://github.com/Data-Everything/MCP-Platform/issues/28 | 来源讨论提到 docker 相关条件，需在安装/试用前复核。

## 8. 安全/权限坑 · 来源证据：[FEATURE] Bigquery mcp server

- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：[FEATURE] Bigquery mcp server
- 对用户的影响：可能影响授权、密钥配置或安全边界。
- 证据：community_evidence:github | https://github.com/Data-Everything/MCP-Platform/issues/20 | 来源讨论提到 python 相关条件，需在安装/试用前复核。

## 9. 安全/权限坑 · 来源证据：[FEATURE] Replicate postgres template to create new snowflake template

- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：[FEATURE] Replicate postgres template to create new snowflake template
- 对用户的影响：可能影响授权、密钥配置或安全边界。
- 证据：community_evidence:github | https://github.com/Data-Everything/MCP-Platform/issues/41 | 来源讨论提到 python 相关条件，需在安装/试用前复核。

## 10. 安全/权限坑 · 来源证据：[FEATURE] Snowflake MCP server

- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：[FEATURE] Snowflake MCP server
- 对用户的影响：可能影响授权、密钥配置或安全边界。
- 证据：community_evidence:github | https://github.com/Data-Everything/MCP-Platform/issues/24 | 来源讨论提到 python 相关条件，需在安装/试用前复核。

## 11. 安全/权限坑 · 来源证据：[FEATURE] Support for elasticsearch MCP server

- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：[FEATURE] Support for elasticsearch MCP server
- 对用户的影响：可能影响升级、迁移或版本选择。
- 证据：community_evidence:github | https://github.com/Data-Everything/MCP-Platform/issues/33 | 来源讨论提到 npm 相关条件，需在安装/试用前复核。

## 12. 安全/权限坑 · 来源证据：[FEATURE] Trino database template creation

- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：[FEATURE] Trino database template creation
- 对用户的影响：可能影响授权、密钥配置或安全边界。
- 证据：community_evidence:github | https://github.com/Data-Everything/MCP-Platform/issues/36 | 来源讨论提到 python 相关条件，需在安装/试用前复核。

## 13. 维护坑 · issue/PR 响应质量未知

- 严重度：low
- 证据强度：source_linked
- 发现：issue_or_pr_quality=unknown。
- 对用户的影响：用户无法判断遇到问题后是否有人维护。
- 证据：evidence.maintainer_signals | https://github.com/Data-Everything/MCP-Platform | issue_or_pr_quality=unknown

## 14. 维护坑 · 发布节奏不明确

- 严重度：low
- 证据强度：source_linked
- 发现：release_recency=unknown。
- 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。
- 证据：evidence.maintainer_signals | https://github.com/Data-Everything/MCP-Platform | release_recency=unknown

<!-- canonical_name: Data-Everything/MCP-Platform; human_manual_source: deepwiki_human_wiki -->