Codex Project Context MCP

一个可迁移的全局 MCP Server + project-context 技能包。

它根据“项目路径 + 当前任务”选择需要读取的 AGENTS.md、docs、模块路径和决策记录，减少每次任务重复加载整套项目文档。

包含内容

server.py                         MCP stdio 入口
config/settings.json              规则与扫描配置
scanners/                         项目扫描、manifest、匹配、变更分析
context/                          Context Pack 聚合
skills/                           MCP 内置技能索引与推荐实现
skill/project-context/            Codex/兼容客户端的触发技能
install.ps1                       Windows 安装器
install.sh                        macOS/Linux 安装器
mcp-configs/                      Trae/Codex 配置示例
tests/                            无业务项目依赖的端到端测试
documentation/                    架构、变量、权限和测试说明

不包含：项目源码、项目索引、技能索引、虚拟环境、密钥、令牌和本机路径。

Windows 安装

git clone https://github.com/daodaobing/codex-project-context.git
cd codex-project-context
.\install.ps1

安装器会：

1. 在 ~/.codex/context-server 安装 MCP 运行时；
2. 创建独立 Python 虚拟环境并安装 requirements.txt；
3. 将 project-context 安装到 ~/.codex/skills/project-context；
4. 在 ~/.codex/config.toml 注册 context_server；
5. 保留运行时生成的项目索引，不把索引上传到 Git。

需要指定 Python 时：

.\install.ps1 -Python "C:\Path\To\python.exe"

如果只想安装文件、不自动更新 Codex 配置：

.\install.ps1 -SkipConfig

安装后重启 Codex。验证：

codex mcp
& "$env:USERPROFILE\.codex\context-server\.venv\Scripts\python.exe" `
  "$env:USERPROFILE\.codex\context-server\tests\test_server.py"

macOS/Linux 安装

git clone https://github.com/daodaobing/codex-project-context.git
cd codex-project-context
./install.sh

也可以通过 CODEX_HOME 指定 Codex 配置根目录：

CODEX_HOME="$HOME/.codex" ./install.sh

Trae 使用

MCP Server 是跨客户端的稳定部分。把下面配置复制到 Trae 的 MCP 管理面板，并将 YOUR_USER 替换为当前用户名：

{
  "mcpServers": {
    "context_server": {
      "command": "C:\\Users\\YOUR_USER\\.codex\\context-server\\.venv\\Scripts\\python.exe",
      "args": [
        "C:\\Users\\YOUR_USER\\.codex\\context-server\\server.py"
      ]
    }
  }
}

完整示例见 mcp-configs/trae.windows.json。Trae 不同版本的配置入口和 SKILL.md 自动发现方式可能不同；如果版本支持项目级技能，将 skill/project-context 复制到项目的 .trae/skills/project-context，或通过 Trae 的技能/规则界面导入。若当前版本不识别 SKILL.md，将 trae/project-context.rules.md 复制到 Trae 的项目规则中即可。即使不安装技能，只配置 MCP 也可以直接使用所有 Context Tool。

使用方式

普通项目任务：

$project-context

项目路径：C:\Projects\MyProject

任务：修改登录页面并修复 token 过期问题。

技能会要求 Codex/兼容客户端先调用 get_project_context 或 get_context_pack，再使用 Serena 或客户端自身的代码导航能力定位实现。

新项目初始化：

$project-context

项目路径：C:\Projects\NewProject

请先预览初始化上下文文件，只读，不写入。

只有得到明确确认后，才调用 initialize_project_context(..., dry_run=false)。普通上下文加载不会创建或修改项目文件。

context-manifest.yaml

在项目根目录声明项目主动维护的上下文：

project:
  name: My Project
  type: code

modules:
  auth:
    paths:
      - src/core/auth
    documents:
      - docs/contracts/auth.md
    decisions:
      - docs/decisions.md
    keywords:
      - auth
      - login

knowledge_domains:
  billing_rules:
    documents:
      - docs/billing-prd.md
    keywords:
      - billing
      - 计费

modules 只放真实代码模块；没有代码路径的业务知识放 knowledge_domains。新增或修改 manifest 后，调用 scan_project(project_path, force=true) 刷新索引。

Tool

核心 Tool：

• get_project_context
• get_context_pack
• scan_project
• list_projects
• get_project_index
• initialize_project_context
• suggest_projects
• analyze_changes

技能推荐辅助 Tool：

• refresh_skill_registry
• list_skills
• get_skill
• recommend_skills

设计边界

• 不替代 AGENTS.md、项目 docs 或 Serena；
• 第一版规则匹配，不依赖向量数据库、Embedding 或 Agent 框架；
• 索引只存路径、摘要、分类和模块关系，不存源码；
• analyze_changes 只分析，不自动更新文档；
• initialize_project_context 默认 dry-run，写入必须经过确认；
• Server 通过 MCP stdio 运行，不需要公网服务或 API Key。

开发验证

& .\.venv\Scripts\python.exe tests\test_server.py

更详细的架构、变量、权限边界和测试证据见 documentation/。