reposynapse

[!WARNING] Este paquete está deprecado y ya no recibe actualizaciones. Por favor usa la versión actualizada y mejorada: reposynapse

reposynapse

Universal MCP server that analyzes any codebase and provides structured context to AI assistants. Dynamic, accurate, and token-efficient.

What's New in v1.8.0

• Bug fix: diff-aware 0L — modified files added to hotfiles now show real line counts instead of 0L.
• section="modified" in get_project_context — dedicated section for git-modified files only (no mixing with oversized).
• depth=1 in read_file_outline — top-level symbols only. Reduces ~450 tokens to ~80 tokens on complex files.
• Multi-name search_symbol — search multiple symbols at once: "handleDelete,handleEdit".
• Fuzzy match indicator in search_symbol — results now show ~ci (case-insensitive), ~sub (substring), ~fuzzy tags. Header shows (fuzzy — no exact match found) when no exact match exists.
• max_files=-1 default limit in search_in_project — when showing all files, max_results defaults to 5 per file (was 30) to avoid token budget blowup. Override with explicit max_results.

See CHANGELOG.md for previous versions.

Quick Setup

Automatic (recommended)

npm install -g reposynapse

# Run the interactive setup wizard
reposynapse-setup

The wizard will:

1. Detect installed AI tools (Claude Desktop, Cursor, Windsurf, VS Code, Cline, Zed, OpenCode, Codex, Antigravity)
2. Let you select which ones to configure
3. Safely merge reposynapse into their config files (backup created)
4. Show a summary of changes

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

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

Manual Setup

Claude Desktop / Cursor / Windsurf (claude_desktop_config.json / ~/.cursor/mcp.json):

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

VS Code (~/Library/Application Support/Code/User/mcp.json on macOS, %APPDATA%\Code\User\mcp.json on Windows):

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

Usage

Tools (12 exposed — optimized for minimal token overhead)

# ─── 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, outline 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/

Resources (Zero Token Cost!)

MCP Resources are automatically available to AI - no tool call needed:

| Resource | Description | | ---------------------------- | ----------------------------------- | | reposynapse://context/summary | ~50 token summary | | reposynapse://context/full | Complete compact context | | reposynapse://context/stack | Languages & frameworks | | reposynapse://context/structure | Folders & entry points | | reposynapse://context/api | API endpoints | | reposynapse://context/models | Data models | | reposynapse://context/hotfiles | Complex/oversized files | | reposynapse://context/annotations | Business rules & gotchas | | reposynapse://context/imports | Internal dependency graph | | reposynapse://context/outlines | All file outlines (symbols + lines) | | reposynapse://context.json | Full JSON (programmatic) |

Output Formats

Minimal (~50 tokens)

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

Ultra (~165 tokens)

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]

Compact (~350 tokens) - Default

# 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

Zero-Token Auto-Docs (v1.3.0)

On startup, the MCP generates a .reposynapse/ directory with rich markdown docs:

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

The AI reads these files naturally — 0 MCP token cost. A file watcher keeps them updated automatically when you change code (5s debounce).

Hot Files Detection (v1.2.0)

Automatically identifies problematic files based on:

| Criterion | Threshold | Why it matters | | ------------- | --------- | --------------------------------- | | Lines of code | > 300 | File too large to navigate easily | | Import count | > 15 | High coupling | | Export count | > 20 | Too many responsibilities | | TODO density | > 3 | Concentrated tech debt |

Import Graph (v1.2.0)

Analyzes internal import/require statements to build a dependency map:

• Hub files: Most-imported files (core of the system)
• Orphan files: Files nobody imports (possible dead code)
• Mermaid output: Visual diagram with get_project_imports { "format": "mermaid" }

Annotations (v1.2.0)

Manage project knowledge via MCP tools — no manual file editing needed:

# 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 }

Annotations are persisted in .reposynapse-notes.json and included in all context formats.

Smart Caching

• In-memory: 30s TTL for repeated calls
• Disk cache: 1h TTL with file hash validation
• Auto-invalidate: When config files change (package.json, etc.)

The cache file .reposynapse.json is stored in your project root. Add to .gitignore.

Supported Languages

| Language | Deps | Endpoints | Models | | ------------- | -------------------------------- | --------------------------------------- | -------------------------- | | TypeScript/JS | package.json | Express, Fastify, Hono, NestJS, Next.js | Interfaces, Types, Classes | | Python | requirements.txt, pyproject.toml | FastAPI, Flask, Django | Pydantic, Dataclasses | | Rust | Cargo.toml | Actix, Axum, Rocket | Structs, Enums | | Go | go.mod | Gin, Echo, Fiber | Structs | | Java/Kotlin | pom.xml, build.gradle | Spring | Classes, Records | | PHP | composer.json | Laravel, Symfony | Classes | | Ruby | Gemfile | Rails, Sinatra | ActiveRecord | | C#/.NET | .csproj | ASP.NET | Classes, Records | | Swift | Package.swift | Vapor | Structs, Classes | | Dart | pubspec.yaml | - | Classes |

Analysis Includes

• Tech Stack: Languages, frameworks, dependencies, package manager
• Structure: Folders with descriptions, entry points, config files, largest file per folder
• API Endpoints: REST routes, GraphQL operations
• Data Models: Interfaces, types, schemas, database models
• Architecture: MVC, Clean Architecture, Serverless, etc.
• Status: TODOs, tests, CI/CD, Docker
• Hot Files: Oversized, high-import, TODO-dense files
• Import Graph: Hub files, orphan files, dependency map
• Annotations: Business rules, gotchas, warnings (managed via MCP)

Environment Variables

| Variable | Description | Default | | ------------------- | --------------------- | --------------- | | REPOSYNAPSE_ROOT | Project root override | process.cwd() |

Contributing

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

Adding Language Support

1. src/detectors/language.ts - Language detection
2. src/detectors/endpoints.ts - Endpoint patterns
3. src/detectors/models.ts - Model patterns

Adding Detectors

1. src/detectors/hotfiles.ts - Hot file thresholds
2. src/detectors/imports.ts - Import graph patterns
3. src/detectors/annotations.ts - Annotation manager

License

MIT

---

Use less tokens. Know more. Ship faster.