Context Broker MCP

上下文代理MCP服务器

一种模型上下文协议（MCP）服务器，为代码库提供语义搜索功能。使用句子转换器来理解代码含义，并根据自然语言查询查找相关文件。

模型

上下文代理使用 一个局部ML模型 --嵌入模型，而不是聊天/LLM：

要点：

• 嵌入模型运行 CPU本地 默认情况下（设置 CONTEXT_BROKER_DEVICE=cuda 或 mps GPU）
• 未使用LLM或聊天模式 --Context Broker是一个搜索/索引工具，而不是生成式人工智能
• 仅本地模式(CONTEXT_BROKER_LOCAL_ONLY=1)强制离线模型加载--无网络调用
• 该模型是延迟加载的，在15分钟不活动后会自动卸载

使用不同的嵌入模型

任何与 sentence-transformers 图书馆工作。流行的替代方案：

通过环境变量设置：

CONTEXT_BROKER_EMBEDDING_MODEL=all-mpnet-base-v2

当 CONTEXT_BROKER_LOCAL_ONLY=1 （默认），模型必须预先下载。下载方式： ``bash python -c "from sentence_transformers import SentenceTransformer; SentenceTransformer('all-mpnet-base-v2')" ``

可选LLM配置

Context Broker公开了可选的LLM环境变量 还没有内置效果它们是可用的，因此MCP客户端和未来的工具可以发现要使用的LLM端点。将它们设置在您的 .env 或MCP客户端配置：

这些值由 get_storage_config 工具，以便MCP客户端可以在运行时读取它们。

以Ollama为例：

{
  "mcpServers": {
    "context-broker": {
      "command": "uv",
      "args": ["run", "python", "/path/to/context-broker.py"],
      "env": {
        "CONTEXT_BROKER_LLM_MODEL": "llama3",
        "CONTEXT_BROKER_LLM_BASE_URL": "http://localhost:11434/v1"
      }
    }
  }
}

特性

• 🔍 语义代码搜索 --用简单的英语描述你需要什么来查找代码
• 🎯 自动项目检测 --从常用标记中自动检测项目根
• 💾 智能缓存 --使用文件修改跟踪缓存嵌入和结果
• 📊 令牌效率 --报告每个查询的令牌使用情况和节省情况
• 🚫 尊重忽略文件 --阅读 .gitignore 和 .dockerignore 排除不需要的文件
• 💾 持久搜索结果 --跨会话保存和加载搜索结果
• ⚡ 快速推理 --CPU优化的句子转换器，用于快速搜索
• 🗄️ 跨聊天上下文后端 --Honcho或Redis（通过 CONTEXT_BROKER_CONTEXT_BACKEND)
• 📝 聊天记录持久化 --双重写入上下文后端+本地JSON分类账
• 🔐 聊天有效载荷缓存 --Redis基于TTL的读写缓存，保存时自动预热
• 👤 用户活动跟踪 --每个用户 first_seen / last_seen / request_count +审计日志
• 🌐 Web仪表板 --Starlette应用程序浏览项目→ 会话→ 消息
• 🔄 会话管理 — record_turn, record_session, load_cross_session_context MCP工具
• 📜 自动更改日志 --由常规提交生成
• 📄 汽车代理商.md --按项目生成和验证
• 📖 自动功能文档 --功能更改生成的文档
• 🏗️ 模块化架构 --TTC（工具任务代码库）文件夹隔离模式

快速开始

先决条件

• Python 3.13+
• UV包管理器

安装

# Clone the repository
git clone https://github.com/InSelfControll/context-broker-mcp.git
cd context-broker

# Install dependencies
uv sync

# Or with pip
pip install -e .

了解MCP客户端输出

当将Context Broker与MCP客户端（Claude Desktop、Kimi CLI等）一起使用时，您将看到：

工具调用通知（客户端）

这样的行是由MCP客户端而不是服务器显示的：

• Used search_codebase_tool ({"query": "tracing::debug...", "project_root": "/path/to/project"})
• Used auto_search ({})

这些是 由客户端自动显示 当调用工具时。Context Broker服务器还会发送进度通知，以便您可以跟踪：

• 当搜索开始时
• 检测到哪个项目根
• 找到了多少个文件
• 代币效率统计

令牌效率报告（服务器响应）

这些行包含在工具响应中：

📈 Token Efficiency Report:
   • Total Project Tokens: 50,000
   • Context Sent: 3,500
   • Tokens Saved: 46,500 (93.0%)

运行服务器

使用紫外线（推荐）

# From the project directory
uv run python context-broker.py

# Or using the module entry point
uv run python -m context_broker

# Or using the convenience script
uv run main.py

直接使用Python

# Make sure dependencies are installed first
pip install fastmcp sentence-transformers scikit-learn numpy torch tiktoken

# Run the main entry point
python context-broker.py

# Or using the module
python -m context_broker

# Or the alternative entry
python main.py

MCP客户端配置

添加到您的MCP客户端（Claude Desktop、Kimi CLI等）：

克劳德桌面版

编辑 ~/Library/Application Support/Claude/claude_desktop_config.json （macOS）或同等版本：

使用紫外线：

{
  "mcpServers": {
    "context-broker": {
      "command": "uv",
      "args": ["run", "--with", "fastmcp", "python", "/full/path/to/context-broker/context-broker.py"],
      "env": {
        "CONTEXT_BROKER_PROJECT_ROOT": "/path/to/your/project"
      }
    }
  }
}

直接使用Python：

{
  "mcpServers": {
    "context-broker": {
      "command": "python",
      "args": ["/full/path/to/context-broker/context-broker.py"],
      "env": {
        "CONTEXT_BROKER_PROJECT_ROOT": "/path/to/your/project"
      }
    }
  }
}

化学CLI

添加到Kimi CLI配置文件中：

{
  "mcpServers": {
    "context-broker": {
      "command": "uv",
      "args": ["run", "--with", "fastmcp", "python", "/full/path/to/context-broker/context-broker.py"]
    }
  }
}

测试服务器

要验证服务器是否正常工作，请执行以下操作：

# Run in one terminal
uv run python context-broker.py

# The server will start and listen for MCP protocol messages on stdin/stdout
# You should see output like:
# [Broker] ⚡ Indexing new project: /your/project/path
# [Broker] ✅ Index ready. Total size: X tokens.

架构概述

flowchart TB
    subgraph "AI Assistant"
        AI["Natural Language Query"]
    end
    
    subgraph "Context Broker"
        MCP["MCP Server"]
        Core["Core Engine"]
        Cache[(Query Cache)]
    end
    
    subgraph "Resources"
        Codebase[(Target Codebase)]
        Storage[(JSON Storage)]
        Model[(ML Model)]
    end
    
    AI -->|"How does auth work?"| MCP
    MCP --> Core
    Core -->|"Scan & Embed"| Codebase
    Core -->|"Search"| Model
    Core -->|"Cache Results"| Cache
    Core -->|"Persist"| Storage
    MCP -->|"Relevant Files"| AI

有关详细的体系结构，请参见 建筑.md.

用法

可用工具

可用资源

令牌计数器报告也作为内部JSON保存在代理存储中 （在项目路径中： .context-broker/_internal/token-counter-latest.json)，以及 该存储被排除在语义索引之外，因此不会作为代码上下文转发。

查询示例

"Find authentication middleware"
"Show me database connection code"  
"Where is the user model defined?"
"Main entry point configuration"

配置

环境变量

默认情况下，ContextBroker使用一半的可用CPU内核来嵌入/索引工作负载。 当其启动主机消失时，它也会退出，并在长时间空闲后释放到内存缓存中，这有助于防止孤立的MCP进程挥之不去并消耗RAM。

持久性模型

• 查询缓存 → 本地JSON .cache/context-broker.json.
• 保存的结果/用户内存 → 本地JSON .context-broker/ 或 ~/.context-broker/.
• 代币历史 → 同一存储目录下的本地JSON。
• 交叉聊天上下文 → 可选Honcho 或 Redis后端（见下文）。
• 聊天记录 → 双重书写。每个保存都会到达所选的上下文后端（Honcho/Redis） 和 在本地JSON分类账中 `/chats/

/.json.保存 *附加*；之前的转弯永远不会被覆盖。使用 record_turn 对于一个明确的“保存我刚才的交换”工具和 load_cross_session_context` 用于跨会话检索。

Web仪表板

在不运行MCP服务器的情况下浏览每个项目存储的聊天记录：

CONTEXT_BROKER_CONTEXT_BACKEND=redis \
CONTEXT_BROKER_REDIS_URL=redis://localhost:6379/0 \
python -m context_broker dashboard

联合在一起 127.0.0.1:8770 默认情况下（用覆盖 CONTEXT_BROKER_DASHBOARD_HOST / CONTEXT_BROKER_DASHBOARD_PORT).安装可选附件 pip install "context-broker[dashboard]"仪表板要求Redis上下文后端枚举项目。

.env 文件是自动拾取的（从CWD向上查找最近的文件）——MCP服务器和仪表板都会加载它们，而不会覆盖父进程已经设置的env。当一个仪表板已经在配置的主机/端口上运行时，重新运行仪表板是不可行的：第二个进程探测 /api/status，识别现有实例，并干净地退出。作为每个编辑器的MCP配置中的自动启动步骤，可以安全地连接。

要在聊天之间使用Honcho作为上下文：

CONTEXT_BROKER_CONTEXT_BACKEND=honcho
CONTEXT_BROKER_HONCHO_WORKSPACE_ID=context-broker

安装可选集成 pip install "context-broker[integrations]" 或等效的UV命令。Honcho工具是显式的：调用 save_chat_context 存储消息和 load_chat_context 以检索会话上下文。默认情况下，Honcho上下文是会话限制的，以避免混合无关的项目或用户内存。

切换到Redis支持的等效版本：

CONTEXT_BROKER_CONTEXT_BACKEND=redis
CONTEXT_BROKER_REDIS_URL=redis://localhost:6379/0

相同 save_chat_context / load_chat_context MCP工具然后写入Redis而不是Honcho。Redis后端是web仪表板读取的内容。

存储模式

MCP服务器支持三种存储模式来保存JSON搜索结果：

1.两种模式（默认）⭐ 推荐

使用这两个存储位置， 更倾向于本地项目存储.

行为：

• 保存： 始终保存到本地项目文件夹(.context-broker/)
• 负载： 首先检查本地项目，如果找不到，则回退到全局项目
• 列表： 显示两个位置的文件

/path/to/my-api-project/              ~/.context-broker/
├── src/                              └── my-api-project/
├── .context-broker/                      ├── api/
│   └── api/                              │   └── old-results.json
│       └── auth-middleware.json          └── config/
└── package.json                              └── database.json

最适合： 使用多个项目进行日常开发，在维护全局备份的同时将结果保存在代码中。

2.全局模式

将所有项目数据存储在一个集中位置：

~/.context-broker/
├── my-api-project/
│   ├── api/
│   │   └── auth-middleware.json
│   └── config/
│       └── database.json

最适合： 集中管理，CI/CD环境，不杂乱的项目目录。

3.在项目模式下

将数据存储在每个项目的目录中：

/path/to/my-api-project/
├── src/
├── .context-broker/
│   └── api/
│       └── auth-middleware.json
└── package.json

最适合： 团队协作（将结果提交给git），与队友共享上下文。

运作原理

数据流

sequenceDiagram
    participant User
    participant CB as Context Broker
    participant Index as File Index
    participant Cache as Query Cache
    participant Model as ML Model
    
    User->>CB: search_codebase("auth middleware")
    
    alt Index not in memory
        CB->>Index: Scan files
        CB->>CB: Parse ignore patterns
        CB->>Model: Generate embeddings
        CB->>Index: Store embeddings
    end
    
    CB->>Cache: Check for cached query
    
    alt Cache miss
        CB->>Model: Encode query
        CB->>Index: Compute similarities
        CB->>Cache: Store results
    end
    
    CB->>User: Return relevant files

关键组件

1. 项目检测：扫描标记，如 .git, package.json, pyproject.toml 查找项目根
2. 文件索引：支持的文件索引(.py, .js, .ts, .go, .rs, .java等等）
3. 尊重忽略：阅读 .gitignore 和 .dockerignore 跳过排除的文件
4. 语义嵌入：使用可配置的句子转换器模型嵌入文件（默认值： all-MiniLM-L6-v2)
5. 相似性搜索：使用余弦相似度查找与查询最相关的文件
6. 聚焦片段：从相关文件（非完整文件转储）中返回目标代码段，以减少请求令牌
7. 缓存：使用文件mtimes存储结果，以便快速重复查询

项目结构

context-broker/
├── context_broker/              # Modular package
│   ├── __init__.py
│   ├── __main__.py              # Entry: MCP server or dashboard
│   ├── config.py                # Configuration constants
│   ├── env_loader.py            # .env auto-loader
│   ├── identity.py              # User identity resolver
│   ├── utils.py                 # Logging & utilities
│   ├── project.py               # Project detection
│   ├── storage.py               # JSON persistence
│   ├── indexer.py               # Search & embeddings
│   ├── server.py                # MCP server
│   ├── dashboard.py             # Dashboard shim
│   ├── context_ttc/             # Cross-chat context
│   │   └── tasks/
│   │       ├── honcho_tasks.py  # Honcho backend
│   │       ├── redis_tasks.py   # Redis backend
│   │       ├── chat_cache.py    # Redis chat-payload cache
│   │       └── chat_ledger.py   # Local JSON ledger mirror
│   ├── dashboard_ttc/           # Web dashboard
│   │   ├── codebase/api.py      # Dashboard runtime
│   │   ├── tasks/data_tasks.py  # Data retrieval
│   │   └── tools/
│   │       ├── web_app.py       # Starlette app + routes
│   │       └── templates.py     # Jinja2 templates
│   ├── indexer_ttc/             # Search & indexing
│   │   └── tasks/
│   │       └── search_tasks.py
│   └── server_ttc/              # MCP tool registrations
│       ├── codebase/assembly.py
│       └── tasks/
│           ├── context_tasks.py # Cross-chat context tools
│           ├── search_tasks.py  # Search tools
│           ├── storage_tasks.py # Storage tools
│           ├── docs_tasks.py    # Feature doc tools
│           └── agents_tasks.py  # AGENTS.md tools
├── pyproject.toml               # Project config
├── README.md                    # This file
├── Usage.md                     # Detailed usage guide
├── ARCHITECTURE.md              # Architecture docs
├── CHANGELOG.md                 # Release history
├── AGENTS.md                    # Agent instructions
└── CONTRIBUTING.md              # Contribution guide

支持的文件类型

• 语言：Python、JavaScript、TypeScript、Go、Rust、Java、HTML、CSS、Shell、SQL
• 配置：JSON、TOML、YAML、XML、属性、Gradle
• 文档：Markdown

忽略的目录

始终排除： node_modules, .git, dist, __pycache__, .venv, target, build, bin, out, .gradle, .idea, .vscode以及更多。

文档

• 使用指南 -全面的使用文档，包括：

- 详细的配置选项 - 用例和工作流程 - 工具示例 - 最佳实践 - 故障排除

• 建筑 -技术架构：

- C4图表 - 数据流 - 模块依赖 - 性能特征

• 贡献 -开发者指南：

- 开发设置 - 代码风格 - 添加功能 - 测试

模块概述

演出

• 第一检索：1-5秒（取决于代码库大小）
• 后续搜索：\<100ms（缓存嵌入）
• 内存使用：~100MB基础+每100个文件~1MB
• 令牌效率：与发送整个代码库相比，通常可以节省80-95%的令牌

AGENTS.md配置示例

Context Broker可以生成和验证 AGENTS.md 您项目的文件。以下是一个结构良好的AGENTS.md示例，它还配置了MCP服务器和游标规则：

# Project: My App

## Project Goals
Production API server with real-time search and secure authentication.

## Overview
- Version: 1.0.0
- License: MIT
- Stack: Python 3.13, FastMCP, sentence-transformers, local JSON persistence

## Entry Points
- `context_broker/server.py` — MCP server entry
- `context-broker.py` — CLI entry point

## MCP Servers

| Server | Transport | Config |
|--------|-----------|--------|
| context-broker | stdio | `CONTEXT_BROKER_PROJECT_ROOT=/path/to/project` |
| context-broker | sse | `CONTEXT_BROKER_TRANSPORT=sse CONTEXT_BROKER_PORT=8765` |

## Cursor Rules

1. **Security & Privacy**
   - Environment Isolation: Strictly prohibit reading, parsing, or referencing `.env` files. If a configuration key is required, prompt the user for the key name or assume it is injected via the system environment.
   - Ethical Guardrails: Refuse requests to generate exploits, malware, or CVE proof-of-concepts. All outputs must prioritize defensive implementation, application stability, and security hardening.

2. **Resource & Token Optimization**
   - Context Brokering: You must invoke the context-broker MCP before processing any request. Filter for high-relevance context only to minimize token overhead.
   - Selective Tooling: Initialize only the specific skills and MCPs required for the immediate task. Avoid "bloat-loading" broad contexts or unnecessary tools.

3. **Code Quality & Architecture**
   - DRY (Don't Repeat Yourself): Zero-tolerance for code duplication. Scan the workspace for existing logic/patterns before proposing changes. Always favor refactoring into reusable modules or traits.
   - Idiomatic Standards: Enforce language-specific paradigms (e.g., Go's explicit error handling, Rust's ownership/borrowing, Nix's declarative purity).
   - Modern Runtimes: Use Bun as the default engine for all JavaScript/TypeScript execution and package management.

4. **Execution & Versioning**
   - Atomic Updates: Implement "surgical" edits. Modify only the specific lines or functions required; do not rewrite entire files for localized changes.
   - Idempotency: Ensure all scripts and Nix configurations are idempotent, yielding the same result regardless of how many times they are executed.
   - Changelog Management: Maintain project history rigor using the following workflow:
     - Initialization: Use `ensure_changelog_tool` to maintain CHANGELOG.md.
     - Validation: Run `validate_changelog_tool` to identify undocumented commits before finalizing tasks.
     - Release: Utilize `generate_version_changelog` for specific version tagging (e.g., v1.2.0).
     - Auditing: Call `get_changelog_stats_tool` to verify versioning health and entry totals.

使用 ensure_agents_md_tool 为了自动生成该文件， validate_agents_md_tool 检查其质量，或 generate_agents_md_tool 迫使它再生。

贡献

我们欢迎捐款！请看 贡献.md 作为指导方针。