{"_id":"reposynapse","_rev":"4224900","name":"reposynapse","description":"Universal MCP server that analyzes any codebase and provides structured context to AI assistants, saving tokens by eliminating redundant project exploration","dist-tags":{"latest":"1.8.1"},"maintainers":[{"name":"jul879n","email":""}],"time":{"modified":"2026-03-22T21:43:27.000Z","created":"2026-03-16T20:10:56.838Z","1.8.1":"2026-03-16T20:22:06.532Z","1.8.0":"2026-03-16T20:10:56.838Z"},"users":{},"author":{"name":"Jul879n"},"repository":{"type":"git","url":"git+https://github.com/Jul879n/reposynapse.git"},"versions":{"1.8.1":{"name":"reposynapse","version":"1.8.1","description":"Universal MCP server that analyzes any codebase and provides structured context to AI assistants, saving tokens by eliminating redundant project exploration","main":"dist/index.js","types":"dist/index.d.ts","bin":{"reposynapse":"bin/reposynapse.js","reposynapse-setup":"bin/reposynapse-setup.js"},"scripts":{"build":"tsc","dev":"tsc --watch","start":"node dist/index.js","setup":"node bin/reposynapse-setup.js","postinstall":"node bin/reposynapse-setup.js --auto || true","prepublishOnly":"npm run build","test":"node --test tests/**/*.test.mjs tests/**/*.test.js"},"keywords":["mcp","model-context-protocol","ai","context","codebase","analyzer","claude","opencode","token-saver","project-scanner"],"author":{"name":"Jul879n"},"license":"MIT","repository":{"type":"git","url":"git+https://github.com/Jul879n/reposynapse.git"},"bugs":{"url":"https://github.com/Jul879n/reposynapse/issues"},"homepage":"https://github.com/Jul879n/reposynapse#readme","engines":{"node":">=18.0.0"},"dependencies":{"@modelcontextprotocol/sdk":"^1.12.0","glob":"^11.0.0","ignore":"^5.3.0"},"devDependencies":{"@types/node":"^20.0.0","typescript":"^5.4.0"},"gitHead":"e1ecff647becbb75535d00eb08ac125bfebebd14","_id":"reposynapse@1.8.1","_nodeVersion":"22.18.0","_npmVersion":"11.8.0","dist":{"shasum":"1fffddad9aae5bd2f3e53454ece119251f7cb4e8","size":114142,"noattachment":false,"key":"/reposynapse/-/reposynapse-1.8.1.tgz","tarball":"http://registry.cnpm.dingdandao.com/reposynapse/download/reposynapse-1.8.1.tgz"},"_npmUser":{"name":"jul879n","email":"jul.dev03@gmail.com"},"directories":{},"maintainers":[{"name":"jul879n","email":""}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/reposynapse_1.8.1_1773692526347_0.44823388030411393"},"_hasShrinkwrap":false,"_cnpmcore_publish_time":"2026-03-16T20:22:06.532Z","publish_time":1773692526532,"_source_registry_name":"default","_cnpm_publish_time":1773692526532},"1.8.0":{"name":"reposynapse","version":"1.8.0","description":"Universal MCP server that analyzes any codebase and provides structured context to AI assistants, saving tokens by eliminating redundant project exploration","main":"dist/index.js","types":"dist/index.d.ts","bin":{"reposynapse":"bin/reposynapse.js","reposynapse-setup":"bin/reposynapse-setup.js"},"scripts":{"build":"tsc","dev":"tsc --watch","start":"node dist/index.js","setup":"node bin/reposynapse-setup.js","postinstall":"node bin/reposynapse-setup.js --auto || true","prepublishOnly":"npm run build","test":"node --test tests/**/*.test.mjs tests/**/*.test.js"},"keywords":["mcp","model-context-protocol","ai","context","codebase","analyzer","claude","opencode","token-saver","project-scanner"],"author":{"name":"Jul879n"},"license":"MIT","repository":{"type":"git","url":"git+https://github.com/Jul879n/reposynapse.git"},"bugs":{"url":"https://github.com/Jul879n/reposynapse/issues"},"homepage":"https://github.com/Jul879n/reposynapse#readme","engines":{"node":">=18.0.0"},"dependencies":{"@modelcontextprotocol/sdk":"^1.12.0","glob":"^11.0.0","ignore":"^5.3.0"},"devDependencies":{"@types/node":"^20.0.0","typescript":"^5.4.0"},"gitHead":"57f0c7f33a270d81f13317ee4ea80b2df3cdd786","_id":"reposynapse@1.8.0","_nodeVersion":"22.18.0","_npmVersion":"11.8.0","dist":{"shasum":"d977d5f91bf8dceee8e86fb64e733d198a5c9459","size":114147,"noattachment":false,"key":"/reposynapse/-/reposynapse-1.8.0.tgz","tarball":"http://registry.cnpm.dingdandao.com/reposynapse/download/reposynapse-1.8.0.tgz"},"_npmUser":{"name":"jul879n","email":"jul.dev03@gmail.com"},"directories":{},"maintainers":[{"name":"jul879n","email":""}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/reposynapse_1.8.0_1773691856684_0.670240713306359"},"_hasShrinkwrap":false,"_cnpmcore_publish_time":"2026-03-16T20:10:56.838Z","publish_time":1773691856838,"_source_registry_name":"default","_cnpm_publish_time":1773691856838}},"readme":"# reposynapse\n\nUniversal MCP server that analyzes any codebase and provides structured context to AI assistants. Dynamic, accurate, and token-efficient.\n\n## What's New in v1.8.0\n\n- **Bug fix: diff-aware 0L** — modified files added to hotfiles now show real line counts instead of `0L`.\n- **`section=\"modified\"`** in `get_project_context` — dedicated section for git-modified files only (no mixing with oversized).\n- **`depth=1`** in `read_file_outline` — top-level symbols only. Reduces ~450 tokens to ~80 tokens on complex files.\n- **Multi-name `search_symbol`** — search multiple symbols at once: `\"handleDelete,handleEdit\"`.\n- **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.\n- **`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`.\n\nSee [CHANGELOG.md](./CHANGELOG.md) for previous versions.\n\n## Quick Setup\n\n### Automatic (recommended)\n\n```bash\nnpm install -g reposynapse\n\n# Run the interactive setup wizard\nreposynapse-setup\n```\n\nThe wizard will:\n\n1. Detect installed AI tools (Claude Desktop, Cursor, Windsurf, VS Code, Cline, Zed, OpenCode, Codex, Antigravity)\n2. Let you select which ones to configure\n3. Safely merge `reposynapse` into their config files (backup created)\n4. Show a summary of changes\n\n```bash\n# Alternative: use the --setup flag\nreposynapse --setup\n\n# Check current config status (non-interactive)\nreposynapse-setup --status\n```\n\n### Manual Setup\n\n**Claude Desktop / Cursor / Windsurf** (`claude_desktop_config.json` / `~/.cursor/mcp.json`):\n\n```json\n{\n\t\"mcpServers\": {\n\t\t\"reposynapse\": {\n\t\t\t\"command\": \"npx\",\n\t\t\t\"args\": [\"reposynapse\"]\n\t\t}\n\t}\n}\n```\n\n**VS Code** (`~/Library/Application Support/Code/User/mcp.json` on macOS, `%APPDATA%\\Code\\User\\mcp.json` on Windows):\n\n```json\n{\n\t\"servers\": {\n\t\t\"reposynapse\": {\n\t\t\t\"type\": \"stdio\",\n\t\t\t\"command\": \"npx\",\n\t\t\t\"args\": [\"reposynapse\"]\n\t\t}\n\t}\n}\n```\n\n## Usage\n\n### Tools (12 exposed — optimized for minimal token overhead)\n\n```bash\n# ─── Project Context ───\nget_project_context                                # Full context (default: compact)\nget_project_context { \"format\": \"ultra\" }          # Ultra-efficient (~165 tokens)\nget_project_context { \"section\": \"stack\" }         # Specific section only\nget_project_context { \"section\": \"endpoints\" }     # Sections: stack|structure|endpoints|models|status|hotfiles|modified|imports|annotations\nget_project_context { \"section\": \"modified\" }      # Git-modified files only (v1.8.0)\nget_project_context { \"force_refresh\": true }      # Force re-analysis\n\n# ─── Smart File Reading (v1.5.2) ───\nread_file { \"file\": \"src/server.ts\" }              # Smart: full if <200L, outline if >200L\nread_file { \"file\": \"src/server.ts\", \"start_line\": 100, \"end_line\": 150 }  # Range\nread_file_outline { \"file\": \"src/server.ts\" }                    # Outline: all symbols + line ranges\nread_file_outline { \"file\": \"src/server.ts\", \"depth\": 1 }       # Top-level only (~80t vs ~450t) (v1.8.0)\nread_file_symbol { \"file\": \"src/server.ts\", \"symbol\": \"createServer\" }     # Fuzzy match\n\n# ─── Search (v1.5.2+) ───\nsearch_in_file { \"file\": \"src/server.ts\", \"pattern\": \"TODO\" }                       # In-file search\nsearch_in_file { \"file\": \"src/server.ts\", \"pattern\": \"TODO\", \"context_lines\": 3 }   # With context\n\nsearch_in_project { \"pattern\": \"handleRoute\" }                                       # 1-line summary: total matches + top 10 hottest files\nsearch_in_project { \"pattern\": \"export\", \"file_pattern\": \"*.tsx\" }                  # Filter by glob\nsearch_in_project { \"pattern\": \"TODO\", \"max_files\": 5 }                             # Code detail for top 5 files (sorted: code before docs)\nsearch_in_project { \"pattern\": \"TODO\", \"max_files\": 5, \"context_lines\": 2 }         # Detail with context (overlapping ranges merged automatically)\nsearch_in_project { \"pattern\": \"TODO\", \"max_files\": 5, \"max_results\": 10 }          # Max 10 matches per file\n# max_files=-1 defaults to 5 matches/file to avoid token blowup (v1.8.0) — override with max_results\n\n# grep replacement (v1.6.6) — all files matching glob, grouped + sorted, respects .gitignore\nsearch_in_project { \"pattern\": \"useState\", \"file_pattern\": \"*.ts\", \"max_files\": -1 }\nsearch_in_project { \"pattern\": \"invokeLambda\", \"file_pattern\": \"*.tsx\", \"max_files\": -1, \"context_lines\": 2 }\n\n# exclude docs/markdown from results (v1.7.0)\nsearch_in_project { \"pattern\": \"handleRoute\", \"exclude_pattern\": \"*.md\" }\nsearch_in_project { \"pattern\": \"TODO\", \"exclude_pattern\": \"*.md,docs/**\", \"max_files\": 5 }\n\n# ─── Global Symbol Search (v1.7.0+) ───\nsearch_symbol { \"name\": \"createServer\" }                                      # Find symbol across project (fuzzy)\nsearch_symbol { \"name\": \"User\", \"type\": \"interface\" }                         # Filter by type\nsearch_symbol { \"name\": \"handle\", \"exported_only\": true }                     # Only exported symbols\nsearch_symbol { \"name\": \"handleDelete,handleEdit\" }                           # Multi-name search (v1.8.0)\n\n# ─── File Listing (v1.5.2) ───\nlist_files                                          # Project root\nlist_files { \"path\": \"src\", \"pattern\": \"*.ts\" }     # Filtered\n\n# ─── Annotations ───\nannotate { \"action\": \"list\" }\nannotate { \"action\": \"add\", \"category\": \"businessRules\", \"text\": \"...\" }\nannotate { \"action\": \"remove\", \"category\": \"gotchas\", \"index\": 0 }\n\n# ─── Diagnostics (v1.6.1) ───\nget_diagnostics                                     # Auto-detects language, runs checker, returns ONLY fatal errors\n\n# ─── Docs ───\ngenerate_project_docs                               # Force regenerate .reposynapse/\n```\n\n### Resources (Zero Token Cost!)\n\nMCP Resources are automatically available to AI - no tool call needed:\n\n| Resource                     | Description                         |\n| ---------------------------- | ----------------------------------- |\n| `reposynapse://context/summary`     | ~50 token summary                   |\n| `reposynapse://context/full`        | Complete compact context            |\n| `reposynapse://context/stack`       | Languages & frameworks              |\n| `reposynapse://context/structure`   | Folders & entry points              |\n| `reposynapse://context/api`         | API endpoints                       |\n| `reposynapse://context/models`      | Data models                         |\n| `reposynapse://context/hotfiles`    | Complex/oversized files             |\n| `reposynapse://context/annotations` | Business rules & gotchas            |\n| `reposynapse://context/imports`     | Internal dependency graph           |\n| `reposynapse://context/outlines`    | All file outlines (symbols + lines) |\n| `reposynapse://context.json`        | Full JSON (programmatic)            |\n\n## Output Formats\n\n### Minimal (~50 tokens)\n\n```\nmy-app:typescript+nextjs [src/app/components/lib] entry:src/index.ts\n```\n\n### Ultra (~165 tokens)\n\n```\nmy-app|typescript|nextjs\n[src:45(⚠page.tsx:1200L) app:20 components:15 lib:8]\n→src/index.ts,src/app/page.tsx\nAPI(12):G:/api/users P:/api/auth\nM(5):User,Post,Comment\n⚠3hot|hub:store/index.ts(←12)|rules:2|gotchas:1\n[docs|test:25|docker|ci:github]\n```\n\n### Compact (~350 tokens) - Default\n\n```\n# my-app (typescript)\nA modern web application\n\nStack: typescript, Next.js, React, pnpm\nDeps: next, react, prisma, zod\n\nStructure:\n  src/ (45) - Source code ⚠page.tsx:1200L\n  app/ (20) - Next.js app router\n  components/ (15) - UI components\nEntry: src/index.ts, src/app/page.tsx\n\nAPI (12):\n  GET /api/users → src/app/api/users/route.ts:5\n  POST /api/auth → src/app/api/auth/route.ts:10\n\nModels (5):\n  User (model): id, email, name...\n  Post (model): id, title, content...\n\n⚠ Hot Files (3):\n  src/app/page.tsx (1200L) - oversized\n  src/store/index.ts (800L) - oversized,high-imports\n\nImport hubs: store/index.ts(←12), utils/api.ts(←9)\nOrphans: legacy/parser.ts, utils/deprecated.ts\n\n???? Business Rules:\n  - Schedules: ≥1min separation\n⚠ Gotchas:\n  - page.tsx: 1200+ lines, read by sections\n\nStatus: tests:25 | docker | ci:github | todos:3\n```\n\n## Zero-Token Auto-Docs (v1.3.0)\n\nOn startup, the MCP generates a `.reposynapse/` directory with rich markdown docs:\n\n```\nyour-project/\n├── .reposynapse/\n│   ├── ARCHITECTURE.md     ← Stack, frameworks, deps, patterns\n│   ├── COMPONENTS.md       ← Folders, entry points, hot files, endpoints\n│   ├── MODELS.md           ← All data models with fields\n│   ├── IMPORTS.md          ← Hub files, orphans, mermaid diagram\n│   ├── OUTLINES.md         ← All symbols with line ranges (v1.5.0)\n│   └── STATUS.md           ← TODOs, CI/CD, Docker, annotations\n```\n\nThe AI reads these files naturally — **0 MCP token cost**. A file watcher keeps them updated automatically when you change code (5s debounce).\n\n## Hot Files Detection (v1.2.0)\n\nAutomatically identifies problematic files based on:\n\n| Criterion     | Threshold | Why it matters                    |\n| ------------- | --------- | --------------------------------- |\n| Lines of code | > 300     | File too large to navigate easily |\n| Import count  | > 15      | High coupling                     |\n| Export count  | > 20      | Too many responsibilities         |\n| TODO density  | > 3       | Concentrated tech debt            |\n\n## Import Graph (v1.2.0)\n\nAnalyzes internal `import`/`require` statements to build a dependency map:\n\n- **Hub files**: Most-imported files (core of the system)\n- **Orphan files**: Files nobody imports (possible dead code)\n- **Mermaid output**: Visual diagram with `get_project_imports { \"format\": \"mermaid\" }`\n\n## Annotations (v1.2.0)\n\nManage project knowledge via MCP tools — no manual file editing needed:\n\n```bash\n# Add a business rule\nadd_annotation { \"category\": \"businessRules\", \"text\": \"Orders require payment before shipping\" }\n\n# Add a gotcha\nadd_annotation { \"category\": \"gotchas\", \"text\": \"UserService.ts has 2000+ lines, read by sections\" }\n\n# List all with indices\nlist_annotations\n\n# Remove by index\nremove_annotation { \"category\": \"gotchas\", \"index\": 0 }\n```\n\nAnnotations are persisted in `.reposynapse-notes.json` and included in all context formats.\n\n## Smart Caching\n\n- **In-memory**: 30s TTL for repeated calls\n- **Disk cache**: 1h TTL with file hash validation\n- **Auto-invalidate**: When config files change (package.json, etc.)\n\nThe cache file `.reposynapse.json` is stored in your project root. Add to `.gitignore`.\n\n## Supported Languages\n\n| Language      | Deps                             | Endpoints                               | Models                     |\n| ------------- | -------------------------------- | --------------------------------------- | -------------------------- |\n| TypeScript/JS | package.json                     | Express, Fastify, Hono, NestJS, Next.js | Interfaces, Types, Classes |\n| Python        | requirements.txt, pyproject.toml | FastAPI, Flask, Django                  | Pydantic, Dataclasses      |\n| Rust          | Cargo.toml                       | Actix, Axum, Rocket                     | Structs, Enums             |\n| Go            | go.mod                           | Gin, Echo, Fiber                        | Structs                    |\n| Java/Kotlin   | pom.xml, build.gradle            | Spring                                  | Classes, Records           |\n| PHP           | composer.json                    | Laravel, Symfony                        | Classes                    |\n| Ruby          | Gemfile                          | Rails, Sinatra                          | ActiveRecord               |\n| C#/.NET       | .csproj                          | ASP.NET                                 | Classes, Records           |\n| Swift         | Package.swift                    | Vapor                                   | Structs, Classes           |\n| Dart          | pubspec.yaml                     | -                                       | Classes                    |\n\n## Analysis Includes\n\n- **Tech Stack**: Languages, frameworks, dependencies, package manager\n- **Structure**: Folders with descriptions, entry points, config files, largest file per folder\n- **API Endpoints**: REST routes, GraphQL operations\n- **Data Models**: Interfaces, types, schemas, database models\n- **Architecture**: MVC, Clean Architecture, Serverless, etc.\n- **Status**: TODOs, tests, CI/CD, Docker\n- **Hot Files**: Oversized, high-import, TODO-dense files\n- **Import Graph**: Hub files, orphan files, dependency map\n- **Annotations**: Business rules, gotchas, warnings (managed via MCP)\n\n## Environment Variables\n\n| Variable            | Description           | Default         |\n| ------------------- | --------------------- | --------------- |\n| `REPOSYNAPSE_ROOT` | Project root override | `process.cwd()` |\n\n## Contributing\n\n```bash\ngit clone https://github.com/Jul879n/reposynapse\ncd reposynapse\nnpm install\nnpm run build\n```\n\n### Adding Language Support\n\n1. `src/detectors/language.ts` - Language detection\n2. `src/detectors/endpoints.ts` - Endpoint patterns\n3. `src/detectors/models.ts` - Model patterns\n\n### Adding Detectors\n\n4. `src/detectors/hotfiles.ts` - Hot file thresholds\n5. `src/detectors/imports.ts` - Import graph patterns\n6. `src/detectors/annotations.ts` - Annotation manager\n\n## License\n\nMIT\n\n---\n\n**Use less tokens. Know more. Ship faster.**\n","_attachments":{},"homepage":"https://github.com/Jul879n/reposynapse#readme","bugs":{"url":"https://github.com/Jul879n/reposynapse/issues"},"license":"MIT"}