Codeaware MCP

🧠 代码感知mcp

🇩🇪 德语版本： README.de.md

Local-first AI Code Intelligence, Token Compression, Progressive Memory, Semantic Repository Runtime & Quality Layer for MCP Agents

______________________________________________________________________

🚀 什么是代码感知mcp？

codeaware-mcp 是一个 本地首次MCP运行时 用于AI编码代理，如Claude Code、Codex风格的代理、Cursor/OpenCode风格的工作流、Gemini CLI风格的代理和本地LLM工作流。

它位于代理和存储库之间，并返回 压缩、结构化、基于证据的代码智能 而不是原始文件、嘈杂的终端输出、重复的差异和未测量的令牌使用。

目前的项目最好描述为：

本地第一个持久代码智能运行时，具有稳定的压缩基础和用于有界AI编码代理的v4语义上下文内核。

核心思想很简单：

The LLM should not own repository context.
CodeAware should.

______________________________________________________________________

🧠 为什么存在

现代人工智能编码工具功能强大，但其中许多仍然通过将存储库文本反复加载到LLM上下文窗口中来工作。

这就产生了五个问题：

1. 代币销毁 --相同的文件被一次又一次地读取。
2. 上下文漂移 --模型忘记了压缩后文件的重要性。
3. 可追溯性弱 --很难知道为什么选择了一个文件。
4. 任务边界差 --自主代理过度探索，而不是执行有界补丁。
5. 没有持久存储库语义 --每节课都从原始文本中重建理解。

CodeAware v4解决了根本问题：

Do not make the LLM rediscover the repository.
Compile the repository into reusable semantic intelligence first.

______________________________________________________________________

🧠 CodeAware v4内核

CodeAware v4添加了一个持久的语义存储库层，旨在减少人工智能编码令牌浪费、不受控制的存储库扫描和重复的上下文再水合。

v4执行模型

Repository
→ Discovery
→ AST Parsing
→ Semantic Extraction
→ SemanticIndex
→ SemanticContextAssembler
→ ContextPackage
→ Agent
→ Trace
→ Recovery
→ Architecture Memory
→ Semantic Routing

已实现v4运行时模块

src/v4/
  architecture_memory.rs
  budget.rs
  cache.rs
  cache_invalidation.rs
  call_graph.rs
  context.rs
  context_items.rs
  contracts.rs
  discovery.rs
  errors.rs
  impact.rs
  import_graph.rs
  index_builder.rs
  language_support.rs
  precision.rs
  ranking.rs
  recovery.rs
  retrieval.rs
  semantic_context.rs
  semantic_index.rs
  semantic_router.rs
  semantic_tools.rs
  storage.rs
  summaries.rs
  symbols.rs
  tests_graph.rs
  tokens.rs
  tools.rs
  trace.rs

v4功能

______________________________________________________________________

🔌 v4 MCP工具

以下v4工具已连接到MCP中 tools/call 调度员：

codeaware.get_task_context
codeaware.find_symbol
codeaware.find_callers
codeaware.find_tests
codeaware.diff_impact

codeaware.get_task_context

为AI编码任务构建一个有界的语义上下文包。

{
  "jsonrpc": "2.0",
  "id": 10,
  "method": "tools/call",
  "params": {
    "name": "codeaware.get_task_context",
    "arguments": {
      "repo_root": "/workspace/project",
      "goal": "Refactor semantic context assembly"
    }
  }
}

codeaware.find_symbol

从语义索引中查找符号。

{
  "jsonrpc": "2.0",
  "id": 11,
  "method": "tools/call",
  "params": {
    "name": "codeaware.find_symbol",
    "arguments": {
      "repo_root": "/workspace/project",
      "query": "ContextPackage"
    }
  }
}

codeaware.find_callers

查找符号的调用者。

{
  "jsonrpc": "2.0",
  "id": 12,
  "method": "tools/call",
  "params": {
    "name": "codeaware.find_callers",
    "arguments": {
      "repo_root": "/workspace/project",
      "symbol": "build_context"
    }
  }
}

codeaware.find_tests

查找与符号相关的测试。

{
  "jsonrpc": "2.0",
  "id": 13,
  "method": "tools/call",
  "params": {
    "name": "codeaware.find_tests",
    "arguments": {
      "repo_root": "/workspace/project",
      "symbol": "ContextPackage"
    }
  }
}

codeaware.diff_impact

估计更改文件的语义影响。

{
  "jsonrpc": "2.0",
  "id": 14,
  "method": "tools/call",
  "params": {
    "name": "codeaware.diff_impact",
    "arguments": {
      "repo_root": "/workspace/project",
      "changed_path": "src/v4/tools.rs"
    }
  }
}

______________________________________________________________________

⚖️ 与AI编码工具的比较

CodeAware并没有试图取代AI编码代理。这是 它们下面的语义上下文层.

最佳设置：

Cursor / Claude Code / Gemini CLI / OpenCode
        ↓
CodeAware MCP
        ↓
SemanticIndex + ContextPackage + Budget + Trace
        ↓
Repository

______________________________________________________________________

🧩 典型使用案例

1.减少克劳德代码代币消耗

与其让代理检查整个存储库，不如先问CodeAware：

codeaware.get_task_context(goal="Fix login session handling")

然后将返回的上下文包提供给代理。

2.准确找到符号所在的位置

codeaware.find_symbol(query="ContextPackage")

这避免了加载无关的文件。

3.编辑前查找呼叫者

codeaware.find_callers(symbol="build_context")

在重构、重命名和行为更改之前很有用。

4.查找相关测试

codeaware.find_tests(symbol="ContextPackage")

有助于最小化测试选择。

5.估计变更影响

codeaware.diff_impact(changed_path="src/v4/tools.rs")

在提交或要求模型进行有风险的编辑之前很有用。

______________________________________________________________________

🧱 设计原则

1.上下文归运行时所有

模型不应自由决定读取存储库的多少内容。

Agent requests context.
CodeAware decides what context is allowed.

2.语义优先，文件摘要次之

CodeAware首先尝试语义上下文：

symbols → imports → calls → tests → impact

只有当没有语义上下文可用时，它才会回退到文件摘要。

3.有限执行

每个任务都应该有限制：

max files read
max files changed
max tool calls
max context tokens
stop conditions

4.追踪一切

每个上下文包都应该是可解释的：

Why was this file selected?
Why was this path excluded?
How many estimated tokens were used?

5.默认情况下，本地优先

存储库智能应该是可用的，而无需将整个代码库发送给外部服务。

______________________________________________________________________

🧪 地位诚实

实现了v4架构、运行时模块、语义API和MCP调度器连接。

但是，只有在CI/CD构建验证后，存储库才可用于生产。

当前真相：

Implemented: yes
Documented: yes
MCP-dispatch wired: yes
CI workflow added: yes
CI green: must be verified from GitHub Actions after workflow execution

在本地运行：

cargo fmt --all -- --check
cargo clippy --all-targets --all-features -- -D warnings
cargo test --all --all-features
cargo build --release --all-features

______________________________________________________________________

⚡ 快速开始

1.克隆存储库

git clone https://github.com/mhmtbsbyndr/codeaware-mcp.git
cd codeaware-mcp

2.构建MCP服务器

cargo build --release

二进制文件将在以下网址提供：

./target/release/codeaware-mcp

3.运行测试

cargo test

4.通过stdio在本地运行

./target/release/codeaware-mcp

服务器说话 基于stdio的JSON-RPC正如MCP客户所期望的那样。

5.可选：保持仪表板在后台运行（macOS/Linux）

chmod +x scripts/setup-codeaware-mcp-dashboard-launchd.sh
./scripts/setup-codeaware-mcp-dashboard-launchd.sh install /usr/local/bin/codeaware-mcp

有用的后续行动：

• ./scripts/setup-codeaware-mcp-dashboard-launchd.sh stop
• ./scripts/setup-codeaware-mcp-dashboard-launchd.sh start
• ./scripts/setup-codeaware-mcp-dashboard-launchd.sh uninstall

支持的操作系统：

• macOS：启动代理（已启动）
• Linux（用户系统d）：系统d用户单元

Linux使用情况：

./scripts/setup-codeaware-mcp-dashboard-launchd.sh install /home/$USER/.cargo/bin/codeaware-mcp

要验证，请致电MCP xray 工具并打开返回的URL（例如 http://127.0.0.1:9847).

6.将其添加到克劳德代码/MCP配置中

示例 .mcp.json:

{
  "mcpServers": {
    "codeaware": {
      "command": "/absolute/path/to/codeaware-mcp/target/release/codeaware-mcp",
      "args": [],
      "env": {}
    }
  }
}

配置MCP客户端时，请为二进制文件使用绝对路径。

______________________________________________________________________

✅ 需求

推荐设置：

rustup update
cargo build --release
cargo test

______________________________________________________________________

🧭 为什么v4很重要

AI编码代理经常在以下方面浪费上下文：

Read("src/server.rs")       -> hundreds of source lines
Run("cargo test")           -> hundreds of noisy log lines
Read("src/server.rs") again -> same content again
Context compaction           -> working memory disappears

CodeAware v4朝着以下方向发展：

codeaware.get_task_context   -> bounded semantic context package
codeaware.find_symbol        -> symbol-level retrieval
codeaware.find_callers       -> caller graph lookup
codeaware.find_tests         -> related tests
codeaware.diff_impact        -> impact-aware reasoning
semantic_router              -> cheap/balanced/premium model routing hint
semantic_recovery            -> compact task recovery snapshot

目标不仅仅是减少代币。

目标是 更好、更密集、有界的语义上下文.

______________________________________________________________________

🏗️ 建筑

AI Coding Agent
      |
      v
MCP JSON-RPC / stdio
      |
      v
codeaware-mcp Runtime
      |
      +-- Stable Compression Layer
      |     +-- smart_read
      |     +-- smart_run
      |     +-- git intelligence
      |
      +-- v4 Persistent Code Intelligence Kernel
      |     +-- task contracts
      |     +-- budget engine
      |     +-- discovery/ranking
      |     +-- summaries/token estimation
      |     +-- context packages
      |     +-- semantic index
      |     +-- symbols/imports/calls/tests
      |     +-- impact analysis
      |     +-- architecture memory
      |     +-- semantic recovery
      |     +-- semantic router
      |
      +-- Token Runtime
      |     +-- token_stats
      |     +-- token_savings_report
      |     +-- benchmark_compression
      |
      +-- Context Optimization Runtime
      |     +-- get_relevant_code
      |     +-- code_search
      |     +-- get_relevant_test_errors
      |     +-- get_project_context
      |     +-- tool_manager
      |
      +-- Progressive Memory Foundation
      |     +-- compact memory index
      |     +-- timeline window
      |     +-- observation details
      |     +-- privacy tag filtering
      |     +-- memory citations
      |
      +-- Safety Foundation
            +-- security policy
            +-- command validation
            +-- path validation
            +-- MCP routing

______________________________________________________________________

🧪 验证服务器

运行测试：

cargo test

手动启动二进制文件：

./target/release/codeaware-mcp

JSON-RPC初始化调用示例：

{"jsonrpc":"2.0","id":1,"method":"initialize","params":{}}

现有工具调用示例：

{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"token_stats","arguments":{}}}

示例v4语义工具调用：

{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"codeaware.get_task_context","arguments":{"repo_root":".","goal":"Explain v4 semantic context"}}}

______________________________________________________________________

🗂️ v4文档

v4架构记录在：

docs/CODEAWARE_V4_MASTERPLAN.md
docs/CODEAWARE_V4_ROADMAP.md
docs/CODEAWARE_V4_PHASE1_IMPLEMENTATION_SPEC.md
docs/CODEAWARE_V4_IMPLEMENTATION_SNAPSHOT.md
docs/CODEAWARE_V4_PHASE2_STATUS.md
docs/CODEAWARE_V4_FINAL_ARCHITECTURE.md
docs/CODEAWARE_V4_MCP_TOOLS.md

______________________________________________________________________

🚦 当前状态

CodeAware目前有：

• 真正的Rust机箱结构，
• 真实的MCP stdio服务器，
• 为现有工具提供真正的JSON-RPC调度，
• v4语义MCP工具调度，
• 稳定的压缩导向MCP工具，
• 运行时有线令牌/质量/基准/上下文工具，
• 渐进记忆基础，
• v4语义代码智能运行时基础，
• 语义优先上下文组装API，
• 持久语义存储库内核设计。

剩余的生产硬化任务：

- run full cargo test in CI/local environment
- fix any compile/test regressions if found
- extend tree-sitter support beyond Rust extraction
- add production-grade AST call extraction
- improve semantic index cache invalidation strategy

______________________________________________________________________

🛣️ 路线图

短期

• 确认GitHub操作CI为绿色。
• 拧紧 tools/list v4工具的元数据。
• 改进语义索引持久性和缓存失效。
• 添加令牌节省与原始文件读取的基准。

中期

• 添加TypeScript/JavaScript/Python/PHP/Go/Swift/Java提取。
• 将启发式调用图替换为AST感知的调用提取。
• 通过更丰富的查询支持来持久化架构内存和决策。
• 添加跨提交的语义差异。

长期

• 基于语义复杂性的多模型路由。
• 持久跨存储库内存。
• 语义任务规划器。
• 最少的测试选择。
• IDE/LSP集成。

______________________________________________________________________

🧩 发展理念

每个功能都应该至少降低其中一项成本：

• 重复上下文读取，
• 噪声终端输出，
• 丢失会话内存，
• 不安全的编辑，
• 代码影响不明确，
• 无法证实的人工智能声称，
• 工具模式过载，
• 交叉回购盲，
• 过度压缩导致的质量损失，
• 不受控制的语义漂移。

codeaware-mcp 不仅仅是代币更少。

这关系到 更好的令牌和持久的语义代码智能.