Repo Context MCP

reposynapse

通用MCP服务器，分析任何代码库并为AI助手提供结构化上下文。动态、准确、令牌高效。

v1.8.0的新增功能

• Bug修复：差异感知0L --添加到hotfiles的修改文件现在显示实际行数，而不是 0L.
• section="modified" 在 get_project_context --仅用于git修改文件的专用部分（不与超大文件混合）。
• depth=1 在 read_file_outline --仅限顶级符号。将复杂文件上的约450个令牌减少到约80个令牌。
• 多名称 search_symbol --一次搜索多个符号： "handleDelete,handleEdit".
• 模糊匹配指示器 在 search_symbol --结果现在显示 ~ci 不区分大小写 ~sub （子字符串）， ~fuzzy 标签。标题显示 (fuzzy — no exact match found) 当不存在完全匹配时。
• max_files=-1 默认限额 在 search_in_project --当显示所有文件时， max_results 默认为每个文件5个（30个），以避免代币预算激增。用显式覆盖 max_results.

看 更改日志.md 对于以前的版本。

快速设置

自动（推荐）

npm install -g reposynapse

# Run the interactive setup wizard
reposynapse-setup

向导将：

1. 检测已安装的AI工具（Claude Desktop、Cursor、Windsurf、VS Code、Cline、Zed、OpenCode、Codex、Antigravity）
2. 让您选择要配置的选项
3. 安全合并 reposynapse 进入他们的配置文件（已创建备份）
4. 显示更改摘要

# Alternative: use the --setup flag
reposynapse --setup

# Check current config status (non-interactive)
reposynapse-setup --status

手动设置

克劳德桌面/光标/风帆 (claude_desktop_config.json / ~/.cursor/mcp.json):

{
	"mcpServers": {
		"reposynapse": {
			"command": "npx",
			"args": ["reposynapse"]
		}
	}
}

VS Code (~/Library/Application Support/Code/User/mcp.json 在macOS上， %APPDATA%\Code\User\mcp.json 在Windows上）：

{
	"servers": {
		"reposynapse": {
			"type": "stdio",
			"command": "npx",
			"args": ["reposynapse"]
		}
	}
}

用法

工具（12个已公开——针对最小的令牌开销进行了优化）

# ─── Project Context ───
get_project_context                                # Full context (default: compact)
get_project_context { "format": "ultra" }          # Ultra-efficient (~165 tokens)
get_project_context { "section": "stack" }         # Specific section only
get_project_context { "section": "endpoints" }     # Sections: stack|structure|endpoints|models|status|hotfiles|modified|imports|annotations
get_project_context { "section": "modified" }      # Git-modified files only (v1.8.0)
get_project_context { "force_refresh": true }      # Force re-analysis

# ─── Smart File Reading (v1.5.2) ───
read_file { "file": "src/server.ts" }              # Smart: full if 200L
read_file { "file": "src/server.ts", "start_line": 100, "end_line": 150 }  # Range
read_file_outline { "file": "src/server.ts" }                    # Outline: all symbols + line ranges
read_file_outline { "file": "src/server.ts", "depth": 1 }       # Top-level only (~80t vs ~450t) (v1.8.0)
read_file_symbol { "file": "src/server.ts", "symbol": "createServer" }     # Fuzzy match

# ─── Search (v1.5.2+) ───
search_in_file { "file": "src/server.ts", "pattern": "TODO" }                       # In-file search
search_in_file { "file": "src/server.ts", "pattern": "TODO", "context_lines": 3 }   # With context

search_in_project { "pattern": "handleRoute" }                                       # 1-line summary: total matches + top 10 hottest files
search_in_project { "pattern": "export", "file_pattern": "*.tsx" }                  # Filter by glob
search_in_project { "pattern": "TODO", "max_files": 5 }                             # Code detail for top 5 files (sorted: code before docs)
search_in_project { "pattern": "TODO", "max_files": 5, "context_lines": 2 }         # Detail with context (overlapping ranges merged automatically)
search_in_project { "pattern": "TODO", "max_files": 5, "max_results": 10 }          # Max 10 matches per file
# max_files=-1 defaults to 5 matches/file to avoid token blowup (v1.8.0) — override with max_results

# grep replacement (v1.6.6) — all files matching glob, grouped + sorted, respects .gitignore
search_in_project { "pattern": "useState", "file_pattern": "*.ts", "max_files": -1 }
search_in_project { "pattern": "invokeLambda", "file_pattern": "*.tsx", "max_files": -1, "context_lines": 2 }

# exclude docs/markdown from results (v1.7.0)
search_in_project { "pattern": "handleRoute", "exclude_pattern": "*.md" }
search_in_project { "pattern": "TODO", "exclude_pattern": "*.md,docs/**", "max_files": 5 }

# ─── Global Symbol Search (v1.7.0+) ───
search_symbol { "name": "createServer" }                                      # Find symbol across project (fuzzy)
search_symbol { "name": "User", "type": "interface" }                         # Filter by type
search_symbol { "name": "handle", "exported_only": true }                     # Only exported symbols
search_symbol { "name": "handleDelete,handleEdit" }                           # Multi-name search (v1.8.0)

# ─── File Listing (v1.5.2) ───
list_files                                          # Project root
list_files { "path": "src", "pattern": "*.ts" }     # Filtered

# ─── Annotations ───
annotate { "action": "list" }
annotate { "action": "add", "category": "businessRules", "text": "..." }
annotate { "action": "remove", "category": "gotchas", "index": 0 }

# ─── Diagnostics (v1.6.1) ───
get_diagnostics                                     # Auto-detects language, runs checker, returns ONLY fatal errors

# ─── Docs ───
generate_project_docs                               # Force regenerate .reposynapse/

资源（零代币成本！）

MCP资源自动可供AI使用，无需调用工具：

输出格式

最少（~50个代币）

my-app:typescript+nextjs [src/app/components/lib] entry:src/index.ts

Ultra（约165个代币）

my-app|typescript|nextjs
[src:45(⚠page.tsx:1200L) app:20 components:15 lib:8]
→src/index.ts,src/app/page.tsx
API(12):G:/api/users P:/api/auth
M(5):User,Post,Comment
⚠3hot|hub:store/index.ts(←12)|rules:2|gotchas:1
[docs|test:25|docker|ci:github]

紧凑型（约350个令牌）-默认值

# my-app (typescript)
A modern web application

Stack: typescript, Next.js, React, pnpm
Deps: next, react, prisma, zod

Structure:
  src/ (45) - Source code ⚠page.tsx:1200L
  app/ (20) - Next.js app router
  components/ (15) - UI components
Entry: src/index.ts, src/app/page.tsx

API (12):
  GET /api/users → src/app/api/users/route.ts:5
  POST /api/auth → src/app/api/auth/route.ts:10

Models (5):
  User (model): id, email, name...
  Post (model): id, title, content...

⚠ Hot Files (3):
  src/app/page.tsx (1200L) - oversized
  src/store/index.ts (800L) - oversized,high-imports

Import hubs: store/index.ts(←12), utils/api.ts(←9)
Orphans: legacy/parser.ts, utils/deprecated.ts

📋 Business Rules:
  - Schedules: ≥1min separation
⚠ Gotchas:
  - page.tsx: 1200+ lines, read by sections

Status: tests:25 | docker | ci:github | todos:3

零令牌自动文档（v1.3.0）

启动时，MCP生成 .reposynapse/ 包含丰富markdown文档的目录：

your-project/
├── .reposynapse/
│   ├── ARCHITECTURE.md     ← Stack, frameworks, deps, patterns
│   ├── COMPONENTS.md       ← Folders, entry points, hot files, endpoints
│   ├── MODELS.md           ← All data models with fields
│   ├── IMPORTS.md          ← Hub files, orphans, mermaid diagram
│   ├── OUTLINES.md         ← All symbols with line ranges (v1.5.0)
│   └── STATUS.md           ← TODOs, CI/CD, Docker, annotations

AI自然地读取这些文件-- 0 MCP令牌成本。当您更改代码时，文件监视器会自动更新它们（5s去抖动）。

热文件检测（v1.2.0）

根据以下内容自动识别有问题的文件：

导入图形（v1.2.0）

分析内部 import/require 用于构建依赖关系图的语句：

• 中心文件：大多数导入的文件（系统的核心）
• 孤儿档案：没有人导入的文件（可能是死代码）
• 美人鱼输出：可视化图表 get_project_imports { "format": "mermaid" }

注释（v1.2.0）

通过MCP工具管理项目知识——无需手动编辑文件：

# Add a business rule
add_annotation { "category": "businessRules", "text": "Orders require payment before shipping" }

# Add a gotcha
add_annotation { "category": "gotchas", "text": "UserService.ts has 2000+ lines, read by sections" }

# List all with indices
list_annotations

# Remove by index
remove_annotation { "category": "gotchas", "index": 0 }

注释持久化在 .reposynapse-notes.json 并包含在所有上下文格式中。

智能缓存

• 内存中：30s TTL用于重复呼叫
• 磁盘缓存：1h TTL，带文件哈希验证
• 自动失效：当配置文件更改时（package.json等）

缓存文件 .reposynapse.json 存储在项目根目录中。添加 .gitignore.

支持的语言

分析包括

• 技术栈：语言、框架、依赖关系、包管理器
• 结构：包含描述、入口点、配置文件、每个文件夹最大文件的文件夹
• API终点：REST路由、GraphQL操作
• 数据模型：接口、类型、模式、数据库模型
• 建筑MVC、清洁架构、无服务器等。
• 状态：TODO、测试、CI/CD、Docker
• 热门文件：超大、高导入、TODO密集的文件
• 导入图形：中心文件、孤立文件、依赖关系图
• 注释：业务规则、陷阱、警告（通过MCP管理）

环境变量

贡献

git clone https://github.com/Jul879n/reposynapse
cd reposynapse
npm install
npm run build

添加语言支持

1. src/detectors/language.ts -语言检测
2. src/detectors/endpoints.ts -端点模式
3. src/detectors/models.ts -模型模式

添加探测器

1. src/detectors/hotfiles.ts -热文件阈值
2. src/detectors/imports.ts -导入图形模式
3. src/detectors/annotations.ts -注释管理器

许可证

麻省理工学院

______________________________________________________________________

使用更少的代币。了解更多。船更快。