Cortex MCP

Cortex MCP服务器

AI代理的投资组合内存。\ 将您的真实项目历史转换为任何AI助手都可以实时查询的结构化上下文。

 ](https://nodejs.org/)  

⚠️ 状态：活动MVP --功能齐全，经过测试，但正在积极开发中。欢迎提供反馈和意见。

______________________________________________________________________

目录

• 它是什么
• 它是如何工作的——三层
• 第三方存储库
• 快速开始
• 日常工作流程
• 命令行界面
• 它通过MCP暴露了什么
• 知识存储
• 建筑
• 技术栈
• 发展
• 定位
• 用法示例
• 上下文开销
• 路线图
• 参考文献
• 支持
• 许可证

______________________________________________________________________

它是什么

Cortex MCP是一个实现 模型上下文协议（MCP） --允许AI助手安全访问外部数据的开放标准。

它读取关于项目的综合知识（一个轻量级的邻接知识图，映射应用程序、技术和领域之间的关系；模式；观察；开发人员配置文件），并将其公开为 工具、资源和提示 可由任何MCP兼容试剂消耗。

问题

当您在项目中打开Claude、Copilot或Cursor时，代理不知道：

• 您还有哪些其他项目以及它们之间的联系
• 你更喜欢哪种堆栈，为什么
• 你反复使用哪些模式
• 哪些组件可以重复使用
• 您对每项技术的真实体验

每节课都从头开始-- 健忘症配对程序设计.

解决方案

Cortex为AI代理提供了相同的功能 长期记忆 作为一名开发人员。它在存储库中积累知识，并使其在每个会话中都能立即访问。

_“人工智能是你的镜子——它能更快地揭示你是谁。如果你不称职，它会更快地产生坏事。如果你有能力，它会更快速地产生好事。”_ --秋田

Cortex的工作原理与 您整个投资组合的“CLAUDE.md” --不是一个项目，而是你整个职业生涯。

完全隐私

100%本地，无云，无遥测。你的数据永远不会离开你的机器。

______________________________________________________________________

它是如何工作的——三层

使用前请阅读本节。 大多数用户只使用第1层，觉得系统“肤浅”。真正的价值在于第2层和第3层。

Cortex不是被动学习的。它是一个结构化的知识库——你输入的越多，它就越有用。正确的思维模式： AI代理实时查询的投资组合维基.

第1层——自动扫描仪（约为值的20%）

cortex-mcp scan 自动检测：

• 技术栈（语言、框架、数据库、CI、Docker）
• 提交频率和贡献者历史
• 跨存储库的重复模式
• 初始操作员配置文件

重要限制： 扫描器只看到代码和git历史记录中的内容。它不知道你为什么选择一项技术，你遇到了什么问题，或者你学到了什么。一个项目 1 commit （浅克隆）产生非常差的轮廓。

第2层——通过MCP工具进行治疗（约占价值的60%）

Cortex的真正力量由您在工作会话中提供：

⚠️ 真正的挑战： 第二层是60%的价值所在，但它需要主动记住调用 start_session, track_decision，以及 end_session 每一天。 如果没有刻意的努力，大多数开发人员将无法保持这种习惯。之间的差距 _“已安装”_ 和 _“确实有用”_ 这是真的——Cortex的好坏取决于你对策展的训练。 路线图项目 _“基于会话历史的动态提示”_ 有助于缩小这一差距，但尚未发货。与此同时：设置提醒，或将这些电话作为团队“完成定义”的一部分。

第3层——操作员配置文件（约20%的值）

文件 knowledge/operator-profile.yaml 是开发人员的个人背景。它由扫描仪自动生成，但需要手动策展才能获得真实的内容。直接编辑：

identity:
  name: Your Name
  role: Your Role
  domain: Your areas of expertise
  github: https://github.com/your-username

______________________________________________________________________

第三方存储库

您可以添加第三方存储库（公共或私有）作为分析和比较的来源。

• Cortex将这些信号整合到您的本地上下文中（堆栈、模式、约定、关系）。
• 这使得建议更具情境性，而不是靠魔法“更聪明”。
• 有判断力地使用：尊重许可证、保密性，以及你自己的投资组合和外部参考之间的分离。
• 为了避免混淆。， --name ref-repo-name).

______________________________________________________________________

快速开始

先决条件

• Node.js 20+
• Git

安装和构建

git clone https://github.com/BUGG1N/cortex-mcp.git cortex-mcp
cd cortex-mcp
npm install
npm run build

生成知识

# 1. Initialize the knowledge directory
npx cortex-mcp init

# 2. Add repositories (local, public GitHub, or private with token)
npx cortex-mcp add ./my-project
npx cortex-mcp add https://github.com/user/public-repo
npx cortex-mcp add https://github.com/user/private-repo --token ghp_xxx

# 3. Scan everything → generates knowledge files automatically
npx cortex-mcp scan

# 4. Start the MCP server
npx cortex-mcp

安全性：令牌仅用于验证Git操作，不会写入克隆存储库的远程URL。

⚠️ 从URL克隆的存储库的历史记录很浅。 这会导致扫描仪报告 1 commit 并且降低了所生成的简档的质量。要修复： ``bash cd repos/repo-name && git fetch --unshallow cd ../.. && npx cortex-mcp scan ``

配置您的个人资料（推荐）

第一次扫描后，编辑 knowledge/operator-profile.yaml 添加真实上下文：

identity:
  name: Your Real Name
  role: Your Role (e.g. Founder CTO, Senior Engineer)
  domain: Your domains (e.g. fintech, IoT, healthcare)
  github: https://github.com/your-username

如果没有此选项，配置文件默认为 name: Developer 只有通过提交量才能推断出专业知识。

丰富真实情境（价值所在）

扫描仪生成一个起点。有用的知识来自策展——通过与代理连接的MCP工具：

# Examples of prompts that feed Cortex automatically:
"Record that I chose FastAPI over Flask because I needed native async"
"Add an observation to project-x that the accuracy bottleneck is dataset size, not architecture"
"Start a work session on project-y focused on Sprint 0"

当代理执行这些操作时，Cortex会将知识保存在YAML/JSONL文件中，并在未来的所有会话中提供。

连接到克劳德桌面

添加 claude_desktop_config.json:

{
  "mcpServers": {
    "cortex": {
      "command": "node",
      "args": ["/absolute/path/to/cortex-mcp/dist/cli.js"]
    }
  }
}

窗户：

{
  "mcpServers": {
    "cortex": {
      "command": "node",
      "args": ["C:\\dev\\cortex-mcp\\dist\\cli.js"]
    }
  }
}

macOS/Linux：

{
  "mcpServers": {
    "cortex": {
      "command": "node",
      "args": ["/home/user/cortex-mcp/dist/cli.js"]
    }
  }
}

重新启动克劳德桌面。您将看到“cortex”可用的工具和资源。

连接到VS代码（GitHub Copilot）

选项1——仅限工作区

在 .vscode/mcp.json 在Cortex项目根目录处：

{
  "servers": {
    "cortex": {
      "command": "node",
      "args": ["
/dist/cli.js"]
    }
  }
}

选项2——全球（建议用于投资组合）

使用Cortex 任何VS代码窗口 （例如，打开另一个项目，仍然可以访问完整的知识库），创建全局MCP配置文件：

文件位置：

• 窗户： %APPDATA%\Code\User\mcp.json
• macOS： ~/Library/Application Support/Code/User/mcp.json
• Linux： ~/.config/Code/User/mcp.json

{
  "servers": {
    "cortex": {
      "command": "node",
      "args": ["
/dist/cli.js"],
      "type": "stdio",
      "env": {
        "CORTEX_ROOT": "
"
      }
    }
  }
}

⚠️ CORTEX_ROOT 在全局配置中是必需的。 没有它，Cortex会尝试从当前工作目录中查找根目录(cwd).当VS Code打开另一个项目时 cwd 就是那个项目，Cortex找不到 knowledge/ 文件夹，返回空结果。 CORTEX_ROOT 通过明确指向存储数据的目录来解决这个问题。

替换 使用到Cortex根的绝对路径（例如。， C:\\dev\\CORTEX 在Windows上， /home/user/cortex 在Linux上）。

______________________________________________________________________

日常工作流程

皮质在融入自然发育节奏时最有用，而不仅仅是在初始设置时使用。

开始项目工作

[in the agent chat, Agent mode]
"Start a session on project X focused on [goal]"

start_session 自动注入：项目堆栈、先前观察、相关模式、上次记录的决策和运算符上下文。

工作期间

"Record that I found an N+1 query problem in the /observations endpoint"
"Add the decision to use Alembic instead of manual migrations, reason: traceability"
"Note that the current model accuracy is below the target threshold — the bottleneck is dataset size, not architecture"

完成时

"End the session with summary: [what was done], decisions: [list], next steps: [list]"

数天后返回

"What do you know about project X?" → the agent queries Cortex and summarizes current state
"What were the last decisions on project Y?" → returns curated decisions log
"What is my pattern for Python APIs?" → returns from the knowledge store

定期维护（每周/每两周一次）

# Update GitHub sources
npx cortex-mcp sync

# Re-scan after stack changes
npx cortex-mcp scan

# Diagnostics if something seems wrong
npx cortex-mcp doctor

______________________________________________________________________

命令行界面

cortex-mcp [command] [options]

Commands:
  init                    Initialize knowledge directory with empty files
  add             Add a repository source (local path or GitHub URL)
  scan                    Scan all sources and update the knowledge base
  sync                    Update GitHub sources (pull latest)
  sources                 List all configured sources
  remove            Remove a source
  serve                   Start the MCP server (default if no command given)
  doctor                  Diagnose the environment and knowledge files

Adding sources:
  cortex-mcp add ./local/path                  Local directory
  cortex-mcp add https://github.com/u/repo     Public GitHub repo (auto-clones)
  cortex-mcp add https://github.com/u/repo --token ghp_xxx   Private repo
  cortex-mcp add  --name my-name       Custom name
  cortex-mcp add  --branch develop     Specific branch

Options:
  --root 
   Root directory (auto-detected from cwd)
  --no-watch      Disable file watching for hot-reload
  --help, -h      Show help
  --version, -v   Show version

环境变量：

• CORTEX_ROOT --覆盖根目录
• CORTEX_KNOWLEDGE_PATH --覆盖知识文件路径
• GITHUB_TOKEN --私有存储库的GitHub令牌（替代 --token)

______________________________________________________________________

它通过MCP暴露了什么

工具

阅读 代理在回答问题时会自动使用工具。 策展 工具是积累知识的方式——每次调用都会对YAML/JSONL文件进行持久化处理。

阅读和查询

策展与知识积累 _（主动使用——这才是真正的价值所在）_

资源

提示

______________________________________________________________________

知识存储

Cortex从 knowledge/ 目录。每个文件都有一个来源和预期的实用程序级别：

observations.jsonl 是最重要的文件，也是唯一一个从不自动填充的文件。 一个没有观察的投资组合只检测到堆栈——不记得为什么会这样做。

operator-profile.yaml 是通过以下方式生成的 name: Developer 以及根据承诺量推断的专业知识。 对于真实内容，请手动编辑，添加姓名、域名和个人背景。

示例数据

这 examples/knowledge/ 目录包含一个完整的示例组合，其中包括4个应用程序、14种技术、24种关系、6种模式和7个观察结果。将其用作理解文件结构的参考，或作为您自己作品集的起点。

______________________________________________________________________

建筑

cortex-mcp/
├── src/
│   ├── cli.ts                  # CLI entry point (init, add, scan, sync, serve)
│   ├── config.ts               # Config resolution (flags → yaml → env → defaults)
│   ├── index.ts                # Public API exports
│   ├── server.ts               # MCP server (stdio transport)
│   ├── types.ts                # Core TypeScript types
│   ├── engine/
│   │   ├── knowledge-engine.ts # Orchestrator — load, index, query
│   │   ├── yaml-parser.ts      # YAML/JSONL parsers
│   │   ├── search-index.ts     # MiniSearch full-text index
│   │   ├── graph-traversal.ts  # BFS/DFS graph queries
│   │   ├── file-reader.ts      # Repository file reader
│   │   └── file-watcher.ts     # Hot-reload via Chokidar
│   ├── mcp/
│   │   ├── tools/              # MCP tools
│   │   ├── resources/          # MCP resources
│   │   └── prompts/            # MCP prompts
│   ├── scanner/
│   │   ├── index.ts            # Scanner orchestrator
│   │   └── detectors/          # Stack auto-detection
│   │       ├── package-json.ts # Node.js / TypeScript
│   │       ├── python.ts       # Python (pip, poetry, pipenv)
│   │       ├── java.ts         # Java (Maven, Gradle)
│   │       ├── dotnet.ts       # .NET / C#
│   │       ├── go.ts           # Go (go.mod)
│   │       ├── rust.ts         # Rust (Cargo.toml)
│   │       ├── infra.ts        # Terraform, Kubernetes, Helm
│   │       ├── docker.ts       # Docker / containerization
│   │       ├── ci.ts           # CI/CD (GitHub Actions, GitLab, Jenkins)
│   │       └── git.ts          # Git metadata (commits, contributors)
│   ├── sources/
│   │   └── index.ts            # Source manager (local, GitHub)
│   └── writer/
│       └── index.ts            # Knowledge writer (YAML/JSONL persistence)
├── test/                       # 35 test files, 90 tests
├── package.json
├── tsconfig.json
└── tsup.config.ts

设计原则

1. 零重依赖 --没有数据库，没有Docker，没有云。读取本地文件，通过stdio提供服务。
2. 综合知识，而非原始代码 --代理接收模式、关系和决策，而不是10000行代码。
3. 可推广的 --适用于任何存储库集合，不与特定的组合绑定。
4. 快 --启动时加载到内存中的所有数据。典型响应\ “加载所有这些知识会占用我的上下文窗口吗？”

不，这是证据。

每个会话的令牌预算

令牌计数按实际值测量 start_session 响应序列化为JSON-RPC。如果你的知识库稀疏，你的数字会略低，如果你有密集的操作员配置文件注释，你的数据会更高。

占上下文窗口的百分比

投资回报率

对于≈2%的上下文窗口，你会被注入到每个会话中：

• 活跃项目的完整技术栈
• 上次记录的架构决策及其基本原理
• 所有存储库中的累积模式
• 随时间记录的陷阱和观察结果
• 您的完整运营商配置文件（域、首选项、约定）

与Repomix的典型代码库转储相比（50000-300000个令牌——20万窗口的25-150%）。Cortex为您提供 知识层 --提炼出的“为什么”和“如何”——成本只是粘贴原始源文件的一小部分。

比率： ~1-2%的上下文窗口→ 投资组合范围内存。这是对上下文投资的50-100倍的回报。

______________________________________________________________________

路线图

• \[x\] 多堆栈扫描仪（10种语言/平台）
• \[x\] 29个MCP工具+资源+提示
• \[x\] 在所有处理程序中使用Zod进行运行时验证
• \[x\] 35个文件中的90个测试（快乐路径+错误路径+弹性+并发性+CLI e2e+MCP合约+stdio集成）
• \[x\] CLI doctor 首次使用诊断
• \[x\] GitHub操作CI（节点20+22）
• \[x\] 示例数据目录(examples/knowledge/)
• \[\]嵌入语义搜索（目前为词汇+同义词扩展）
• \[\]自定义探测器的插件生态系统
• \[\]本地web仪表板，用于可视化知识图
• \[\]基于会话历史的动态提示
• \[\]npm发布(npx cortex-mcp init)

______________________________________________________________________

参考文献

______________________________________________________________________

支持

如果Cortex能节省你的时间，可以考虑给我买杯咖啡☕

加密

提示： 使用专门为捐款而创建的钱包——不要使用你的主钱包或交易钱包。对于以太坊，您可以注册一个人类可读的 ENS 名称（例如。 yourname.eth)因此，该地址易于共享和验证。

PIX（巴西）

Chave PIX： 4978dd10-e12d-42e8-8a32-257ad00594e3

您还可以通过以下方式支持该项目：

• ⭐ 对存储库进行标记
• 🐛 通过以下方式报告错误或请求功能 问题
• 🔀 打开拉取请求

______________________________________________________________________

许可证

麻省理工学院