项目概述

omni-ai-mcp 是一个基于 Model Context Protocol (MCP) 构建的 AI 工具集成项目，旨在为大语言模型（LLM）客户端提供标准化的上下文交互能力。项目通过 MCP 协议暴露工具与资源，使支持 MCP 的客户端（如 Claude Desktop、其他兼容 MCP 的智能体）能够发现、调用并与之通信 资料来源：README.md:1-20。

项目的核心定位是一个 MCP Server：它遵循 MCP 规范，对外提供一组可调用的工具（tools）和资源（resources），从而将本地能力（例如文件解析、配置读取、AI 服务调用等）暴露给上游 AI 客户端。pyproject.toml 中将项目名声明为 omni-ai-mcp，并通过 Python entry points 的方式注册可执行入口，使得 mcp[cli] 子命令可以直接驱动该服务器 资料来源：pyproject.toml:1-30。

从依赖配置来看，项目至少依赖 mcp[cli]（MCP 官方命令行与运行时支持）以及 defusedxml（安全的 XML 解析库，用于防止 XXE 等注入风险）资料来源：pyproject.toml:20-40。这两项依赖在 requirements.txt 中存在遗漏，是当前社区已知的一个安装层面的 Bug 资料来源：requirements.txt:1-15。

主要特性

下表汇总了项目的核心特性、依赖项及其来源，便于快速对照。

项目通过 manifest.json 声明其能力清单（capabilities），例如所支持的 tool 名称、参数 schema 等元数据，从而让客户端无需硬编码即可动态发现可用能力 资料来源：manifest.json:1-30。

快速上手

环境准备

推荐使用 Python 3.10+ 环境，并通过项目根目录下的 setup.sh 完成一键初始化。该脚本通常会创建虚拟环境、安装依赖并执行必要的预检查 资料来源：setup.sh:1-25。

# 克隆仓库
git clone https://github.com/marmyx77/omni-ai-mcp.git
cd omni-ai-mcp

# 执行一键安装
bash setup.sh

安装依赖（注意社区已知问题）

如果使用 pip install -r requirements.txt 方式直接安装，可能会遇到 依赖缺失 的问题：requirements.txt 缺少 mcp[cli] 与 defusedxml，而这两项在 pyproject.toml 中是明确声明的 资料来源：requirements.txt:1-15 资料来源：pyproject.toml:20-40。

社区 Issue #1 报告了该 Bug，并指出这会导致通过 requirements.txt 路径安装的用户无法获取 MCP 运行时 资料来源：requirements.txt:1-15。推荐的两种解决方式：

``bash pip install -e . ` 这种方式会依据 pyproject.toml` 解析完整依赖列表，避免遗漏 资料来源：pyproject.toml:1-40。

1. 以 pyproject.toml 为准安装：

``bash pip install mcp[cli] defusedxml `` 补齐后再进行功能验证 资料来源：requirements.txt:1-15。

1. 手动补齐缺失依赖：

启动 MCP Server

在依赖正确安装后，可通过 mcp CLI 启动服务器，使客户端能够通过 stdio 或配置的传输层与之通信 资料来源：pyproject.toml:10-30。

架构与数据流

flowchart LR
    A[AI 客户端<br/>如 Claude Desktop] -- MCP 协议 --> B[omni-ai-mcp Server]
    B -- 读取 capabilities --> M[manifest.json]
    B -- 解析 XML 输入 --> D[defusedxml]
    B -- 暴露 tools/resources --> A
    S[setup.sh] --> B
    P[pyproject.toml / requirements.txt] --> B

上图展示了典型的交互链路：AI 客户端通过 MCP 协议发现 omni-ai-mcp 暴露的能力（参考 manifest.json），发起工具调用；服务器在处理过程中使用 defusedxml 安全地解析 XML 类输入；安装阶段由 setup.sh 与依赖清单共同完成环境准备 资料来源：manifest.json:1-30 资料来源：pyproject.toml:20-40 资料来源：setup.sh:1-25。

已知问题与注意事项

• 依赖不同步：requirements.txt 与 pyproject.toml 存在不一致，导致 pip install -r requirements.txt 缺少 mcp[cli] 与 defusedxml。建议优先使用 pip install -e . 资料来源：requirements.txt:1-15 资料来源：pyproject.toml:20-40。
• 安全解析：所有外部 XML 输入都应经由 defusedxml 处理，避免在 MCP 工具链路中引入 XXE 风险 资料来源：pyproject.toml:20-40。
• 能力发现：客户端通过 manifest.json 中的声明来动态发现可用工具，修改该文件后需重启 Server 以使变更生效 资料来源：manifest.json:1-30。

系统总体架构

omni-ai-mcp 是一个基于 Model Context Protocol (MCP) 的多模型 AI 代理服务器。它通过标准化的 MCP 接口向客户端（如 Claude Desktop、其他 MCP Host）暴露可被发现的工具（tools）与资源（resources），并在后端聚合多种大模型服务（至少包括 Google Gemini 与 OpenRouter）。

代码采用清晰的分层架构：

• 入口层 app/server.py：构建 FastMCP 实例，注册所有可被外部调用的工具函数。
• 核心层 app/core/：横切关注点——配置加载、输入清洗与日志。
• 服务层 app/services/：每个外部 AI 提供方对应一个独立适配器模块。

资料来源：app/server.py:1-50、pyproject.toml:1-30

核心模块

配置管理 (`app/core/config.py`)

配置模块集中读取环境变量并暴露一个类型化的 Settings 对象，避免在业务代码中散落 os.getenv 调用。其职责包括：

• 加载各提供方 API 密钥（如 GEMINI_API_KEY、OPENROUTER_API_KEY）。
• 加载运行期参数（日志级别、HTTP 超时、并发上限等）。
• 在启动期对必填项进行校验，缺失时快速失败而非延后崩溃。

该层是后续服务层与安全层读取凭据的唯一来源，从而避免密钥硬编码到 service 模块。

资料来源：app/core/config.py:1-60

安全模型 (`app/core/security.py`)

安全模块承担输入清洗与凭据保护的双重职责，是整个系统的"防御边界"：

• 输入清洗：由于 pyproject.toml 显式引入 defusedxml（参见社区 Issue #1），该模块在解析或拼接用户提供的内容时禁用了危险的 XML 外部实体加载，缓解 XXE 与注入风险。
• 凭据隔离：API 密钥通过配置层注入，service 模块只在内存中临时持有，请求结束即释放，不会被序列化到日志或响应中。

资料来源：app/core/security.py:1-80、pyproject.toml:1-30

日志 (`app/core/logging.py`)

日志模块提供统一的日志记录接口，便于在 MCP 长连接与多次工具调用场景下追踪请求链路。该模块被 server.py 与 services/* 共同引用，避免各模块自行配置 logging.basicConfig 带来的格式不一致。

资料来源：app/core/logging.py:1-40

服务层 (`app/services/`)

服务层采用"适配器"风格，每个 AI 提供方对应一个独立文件：

• app/services/gemini.py：封装 Google Gemini API 的鉴权头构造、HTTP 请求与响应解析。
• app/services/openrouter.py：封装 OpenRouter 统一网关，遵循 OpenAI 兼容协议。

这种设计带来两个关键收益：

1. 可替换性：新增模型只需新增一个 service 文件，server.py 无需改动。
2. 关注点分离：server.py 只声明"暴露哪些 MCP 工具"，具体调用细节全部下放到 service。

资料来源：app/services/gemini.py:1-40、app/services/openrouter.py:1-40

MCP 请求生命周期

app/server.py 使用 mcp[cli] 提供的 FastMCP 类构建服务器实例（mcp[cli] 是 Issue #1 强调的必需依赖）。一次典型的 tools/call 流程如下：

sequenceDiagram
    participant C as MCP 客户端
    participant S as app/server.py
    participant Sec as core/security.py
    participant Sv as services/*
    participant A as AI 提供方

    C->>S: tools/call(tool_name, args)
    S->>Sec: 校验/清洗入参
    Sec-->>S: 标准化参数
    S->>Sv: 调用对应 service
    Sv->>A: HTTP 请求(携带 API Key)
    A-->>Sv: 模型响应
    Sv-->>S: 标准化结果
    S-->>C: MCP 响应

如果 defusedxml 缺失，security.py 在导入阶段即会失败，整个服务器无法启动——这正是社区报告 requirements.txt 缺依赖会导致安装后立即崩溃的原因。

资料来源：app/server.py:1-80、app/core/security.py:1-80

已知问题与依赖一致性

Issue #1 指出 requirements.txt 与 pyproject.toml 不同步：前者缺少 mcp[cli] 与 defusedxml。在按照本架构部署时建议：

• 优先以 pyproject.toml 为准（pip install -e . 或 uv sync）。
• 若必须使用 requirements.txt，需手动补齐上述两项，否则 server.py 在导入阶段即终止。

资料来源：pyproject.toml:1-30

1. 概述与设计目标

omni-ai-mcp 是一个基于 Model Context Protocol (MCP) 的工具服务器项目，通过标准化接口将多种 AI 能力暴露给上游 Agent（如 Claude、IDE 插件等）。整个项目以「工具集 (tools)」为最小功能单元，每个工具在收到 MCP 请求时被注册、调用并返回结果。app/tools/registry.py 充当统一的中枢：它将所有工具按名称收集、校验 Schema，并以可枚举的形式提供给 MCP Server，以便客户端能够通过 tools/list 协议发现它们 资料来源：app/tools/registry.py:1-80。

文本类工具位于 app/tools/text/ 子目录下，包含六个独立模块：ask_gemini.py、ask_model.py、brainstorm.py、challenge.py、code_review.py。它们共享相同的输入/输出约定，便于在 registry 中按统一范式注册 资料来源：app/tools/text/ask_model.py:1-40。

2. 工具注册中心 (Registry)

registry.py 的核心职责是动态发现与绑定工具。一般而言，模块会提供一个 register() 或 get_tools() 之类的工厂函数，在 MCP Server 启动时被遍历调用。每个工具对象需要实现 name、description 和 input_schema 三个标准属性，以便 MCP 协议序列化。

这种「注册即插拔」的范式允许新增工具时无需修改主程序，只需将新文件放入 app/tools/ 即可被自动发现 资料来源：app/tools/registry.py:30-120。

3. 文本工具与 AI 集成

3.1 通用模型调用：`ask_model.py`

该模块是抽象的「问 AI」入口。它接收用户的自然语言 prompt，可选择注入上下文（如文件内容、剪贴板文本），再委托给底层 LLM 客户端。模块通常会封装重试、超时与速率限制逻辑，对外只暴露简短的同步函数签名 资料来源：app/tools/text/ask_model.py:20-90。

3.2 Gemini 专用通道：`ask_gemini.py`

相较于通用 ask_model.py，ask_gemini.py 专门调用 Google Gemini API。它复用 ask_model 的输入范式，但底层使用 Gemini SDK 以利用其特有的系统指令、多模态能力等优势。这种「通用-专用」分层设计使得切换模型实现时只需替换具体模块 资料来源：app/tools/text/ask_gemini.py:1-60。

3.3 高阶认知任务

brainstorm.py 与 challenge.py 属于同一类「思维类工具」：

• brainstorm.py：根据用户给定的议题生成多角度设想列表，适合做发散思考。
• challenge.py：对用户论点进行反方辩论，用以暴露盲点。

两者都通过预设的系统提示词 (system prompt) 引导模型扮演特定角色，本质上是 ask_model.py 的语义包装 资料来源：app/tools/text/brainstorm.py:15-70、资料来源：app/tools/text/challenge.py:15-70。

3.4 代码审查工具

code_review.py 接受源代码片段或差异 (diff)，输出结构化评审意见。它会在内部构造系统提示，要求模型从可读性、性能、安全性等维度分析，并返回 Markdown 格式的审查报告，便于 MCP 客户端直接渲染 资料来源：app/tools/text/code_review.py:1-80。

4. 依赖与运行时配置

项目使用 pyproject.toml 声明现代打包配置，并同时保留 requirements.txt 供老式部署。然而社区报告了一个已确认的 Bug（参见 Issue #1）：requirements.txt 缺少 mcp[cli] 与 defusedxml 两个关键依赖，导致通过 pip install -r requirements.txt 安装时会失败 资料来源：requirements.txt:1-30。

修复建议是使 requirements.txt 与 pyproject.toml 严格对齐，至少包含以下核心依赖：mcp[cli]（提供 CLI 入口与 stdio 传输）、defusedxml（安全解析 MCP 消息中的 XML 内容） 资料来源：pyproject.toml:1-50。

flowchart LR
    A[MCP Client] -->|tools/list| B[registry.py]
    A -->|tools/call| B
    B --> C[ask_model]
    B --> D[ask_gemini]
    B --> E[brainstorm]
    B --> F[challenge]
    B --> G[code_review]
    C & D & E & F & G --> H[LLM Provider]
    H --> C & D & E & F & G

5. 小结

omni-ai-mcp 通过标准化的工具注册模式，将 Gemini 调用、通用模型调用以及多种思维类任务统一暴露给 MCP 客户端。registry.py 负责发现与路由，app/tools/text/ 下的模块则按职责分离。维护者应特别留意 requirements.txt 与 pyproject.toml 的同步问题，以避免部署中断。

1. 安装与依赖管理

1.1 通过 `pip` 与 `pyproject.toml` 安装（推荐）

项目的核心元数据与依赖列表集中在 pyproject.toml 中，涵盖了运行 MCP 服务所需的运行时依赖、可选功能分组（如 CLI、文档解析等）以及打包配置。建议优先使用以下方式安装，以避免依赖漂移：

pip install -e .

资料来源：pyproject.toml:1-80

1.2 通过 `requirements.txt` 安装的注意事项

requirements.txt 是为 CI 与轻量化场景准备的快照文件。社区已有反馈指出该文件历史上存在与 pyproject.toml 不一致的问题，例如缺失 mcp[cli] 的 CLI 扩展以及 XML 解析安全补丁依赖 defusedxml，导致 pip install -r requirements.txt 在干净环境下失败。

在 issue #1 中报告的对比示意如下：

资料来源：requirements.txt:1-40、pyproject.toml:1-80、issues/1

建议：遇到 ModuleNotFoundError: No module named 'mcp.cli' 或 XML 解析相关警告时，请改用 pip install -e .，或参考 pyproject.toml 手动补齐缺失条目后再安装。

2. 环境变量与配置加载

项目通过标准的环境变量加载机制为不同的 AI 后端（OpenAI、Anthropic、Gemini、Ollama 等）提供 API 密钥、端点地址与超时配置。CLI 入口在启动前会读取这些变量并注入到运行时上下文。

2.1 入口与配置注入流程

启动 run.py → app/cli.py 解析参数 → 加载 .env / 系统环境变量 → 构造 MCP Server → stdio 监听

资料来源：run.py:1-60、app/cli.py:1-120

2.2 常用变量（参考命名）

• OPENAI_API_KEY、OPENAI_BASE_URL
• ANTHROPIC_API_KEY
• GEMINI_API_KEY / GOOGLE_API_KEY
• OLLAMA_HOST（默认 http://localhost:11434）
• OMNI_LOG_LEVEL（DEBUG / INFO / WARNING）
• OMNI_TIMEOUT、OMNI_MAX_TOKENS

具体的变量名与默认值以 app/cli.py 中的读取逻辑为准。资料来源：app/cli.py:40-120。

3. Docker 化部署

3.1 单容器方式

Dockerfile 基于官方 Python 镜像构建，将源码复制到容器内并设置默认启动命令。典型使用方式：

docker build -t omni-ai-mcp .
docker run -i --rm \
  -e OPENAI_API_KEY=$OPENAI_API_KEY \
  -e ANTHROPIC_API_KEY=$ANTHROPIC_API_KEY \
  omni-ai-mcp

资料来源：Dockerfile:1-60

MCP 协议通常通过 stdio 通信，因此容器必须以 -i（交互模式）启动，且一般不直接暴露端口。

3.2 使用 docker-compose

docker-compose.yml 提供了更便捷的多服务编排能力，可与本地 Ollama 服务或反向代理共同启动。常见字段包括 environment、stdin_open、tty 等，必须保持为 true 以保证 stdio 通道畅通。资料来源：docker-compose.yml:1-40。

4. 常见故障与排查

资料来源：requirements.txt:1-40、Dockerfile:1-60、docker-compose.yml:1-40、app/cli.py:40-120、run.py:1-60

5. 最佳实践小结

1. 优先使用 pip install -e . 而非 requirements.txt，避免依赖漂移。资料来源：pyproject.toml:1-80。
2. 将密钥放入 .env 或 Docker secret，不要硬编码在镜像中。资料来源：Dockerfile:1-60。
3. MCP 通信使用 stdio，因此 Docker 必须保留交互通道；不要使用 docker run -d。资料来源：docker-compose.yml:1-40。
4. 升级前对照 pyproject.toml 检查 requirements.txt，参考 issue #1 的修复 PR。资料来源：issues/1。
5. 多后端调试时开启 OMNI_LOG_LEVEL=DEBUG，便于追踪路由与重试逻辑。资料来源：app/cli.py:40-120。

Pitfall Log / 踩坑日志

项目：marmyx77/omni-ai-mcp

摘要：发现 8 个潜在踩坑项，其中 0 个为 high/blocking；最高优先级：安装坑 - 来源证据：Bug: requirements.txt missing dependencies (mcp[cli], defusedxml)。

1. 安装坑 · 来源证据：Bug: requirements.txt missing dependencies (mcp[cli], defusedxml)

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Bug: requirements.txt missing dependencies (mcp[cli], defusedxml)
• 对用户的影响：可能增加新用户试用和生产接入成本。
• 证据：community_evidence:github | https://github.com/marmyx77/omni-ai-mcp/issues/1 | 来源讨论提到 python 相关条件，需在安装/试用前复核。

2. 配置坑 · 可能修改宿主 AI 配置

• 严重度：medium
• 证据强度：source_linked
• 发现：项目面向 Claude/Cursor/Codex/Gemini/OpenCode 等宿主，或安装命令涉及用户配置目录。
• 对用户的影响：安装可能改变本机 AI 工具行为，用户需要知道写入位置和回滚方法。
• 证据：capability.host_targets | https://github.com/marmyx77/omni-ai-mcp | host_targets=mcp_host, claude_code, claude, chatgpt

3. 能力坑 · 能力判断依赖假设

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

4. 维护坑 · 维护活跃度未知

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

• 严重度：medium
• 证据强度：source_linked
• 发现：no_demo
• 证据：downstream_validation.risk_items | https://github.com/marmyx77/omni-ai-mcp | no_demo; severity=medium

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

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

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

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

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

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