synapps-mcp 1.2.0__tar.gz

synapps_mcp-1.2.0/.github/ISSUE_TEMPLATE/bug_report.yml

@@ -0,0 +1,73 @@
+name: Bug Report
+description: Report a bug in Synapps
+labels: ["bug"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Thanks for reporting a bug! Please fill out the sections below so we can reproduce and fix it.
+
+  - type: textarea
+    id: description
+    attributes:
+      label: Description
+      description: A clear description of what the bug is.
+    validations:
+      required: true
+
+  - type: textarea
+    id: reproduction
+    attributes:
+      label: Steps to reproduce
+      description: How can we reproduce this behavior?
+      placeholder: |
+        1. Index a project with `synapps index .`
+        2. Run `synapps callers "MyClass.MyMethod"`
+        3. See error...
+    validations:
+      required: true
+
+  - type: textarea
+    id: expected
+    attributes:
+      label: Expected behavior
+      description: What did you expect to happen?
+    validations:
+      required: true
+
+  - type: textarea
+    id: actual
+    attributes:
+      label: Actual behavior
+      description: What actually happened? Include error messages or output if applicable.
+    validations:
+      required: true
+
+  - type: input
+    id: synapps-version
+    attributes:
+      label: Synapps version
+      description: Output of `pip show synapps | grep Version`
+      placeholder: "0.1.0"
+
+  - type: dropdown
+    id: language
+    attributes:
+      label: Language being indexed
+      options:
+        - C#
+        - Python
+        - TypeScript / JavaScript
+        - Java
+        - Multiple
+        - N/A
+
+  - type: textarea
+    id: environment
+    attributes:
+      label: Environment
+      description: OS, Python version, Docker version, etc.
+      placeholder: |
+        - OS: macOS 14.5
+        - Python: 3.11.9
+        - Docker: 26.1.1

synapps_mcp-1.2.0/.github/ISSUE_TEMPLATE/feature_request.yml

@@ -0,0 +1,44 @@
+name: Feature Request
+description: Suggest a new feature or improvement
+labels: ["enhancement"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Thanks for suggesting a feature! Please describe what you'd like and why.
+
+  - type: textarea
+    id: problem
+    attributes:
+      label: Problem or motivation
+      description: What problem does this solve, or what workflow does it improve?
+      placeholder: "When I try to do X, I have to Y, which is slow / error-prone / impossible because..."
+    validations:
+      required: true
+
+  - type: textarea
+    id: solution
+    attributes:
+      label: Proposed solution
+      description: How would you like this to work? Include example commands, tool signatures, or output if applicable.
+    validations:
+      required: true
+
+  - type: textarea
+    id: alternatives
+    attributes:
+      label: Alternatives considered
+      description: Any workarounds or alternative approaches you've considered.
+
+  - type: dropdown
+    id: area
+    attributes:
+      label: Area
+      options:
+        - CLI
+        - MCP tools
+        - Indexing / graph
+        - Language support
+        - Docker / containers
+        - Documentation
+        - Other

synapps_mcp-1.2.0/.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,19 @@
+## What does this PR do?
+
+<!-- A brief description of the change. -->
+
+## Why?
+
+<!-- What problem does it solve? Link to an issue if applicable (Fixes #123). -->
+
+## How was this tested?
+
+- [ ] Unit tests pass (`pytest tests/unit/ -v`)
+- [ ] Integration tests pass (if applicable)
+- [ ] Manual testing (describe below)
+
+## Checklist
+
+- [ ] Changes are backwards-compatible (or breaking changes are documented)
+- [ ] New code has tests
+- [ ] Commit messages are clear and descriptive

synapps_mcp-1.2.0/.github/workflows/ci.yml

@@ -0,0 +1,30 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.11", "3.12", "3.13"]
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install -e ".[dev]"
+
+      - name: Run unit tests
+        run: pytest tests/unit/ -v

synapps_mcp-1.2.0/.github/workflows/publish.yml

@@ -0,0 +1,63 @@
+name: Publish to PyPI
+
+on:
+  push:
+    tags:
+      - "v*"
+
+jobs:
+  build:
+    name: Build and smoke-test
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: astral-sh/setup-uv@v7
+        with:
+          enable-cache: true
+
+      - name: Build wheel and sdist
+        run: uv build
+
+      - name: Smoke test
+        run: |
+          python3 -m venv /tmp/smoke-venv
+          /tmp/smoke-venv/bin/python -m pip install --quiet dist/*.whl
+          /tmp/smoke-venv/bin/python -c "
+          import synapps
+          import solidlsp
+          import tree_sitter_python
+          import tree_sitter_c_sharp
+          import tree_sitter_typescript
+          import tree_sitter_java
+          print(f'synapps.__version__ = {synapps.__version__!r}')
+          assert synapps.__version__ != 'dev', 'version must not be dev in wheel'
+          print('All imports OK')
+          "
+          /tmp/smoke-venv/bin/synapps --help
+          /tmp/smoke-venv/bin/synapps-mcp --help
+
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    name: Publish to PyPI
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/project/synapps-mcp/
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+      - uses: astral-sh/setup-uv@v7
+
+      - name: Publish to PyPI
+        run: uv publish --trusted-publishing always

synapps_mcp-1.2.0/.gitignore

@@ -0,0 +1,16 @@
+__pycache__/
+*.pyc
+.venv/
+dist/
+*.egg-info/
+.env
+.DS_Store
+*.DS_Store
+.pytest_cache/
+htmlcov/
+.coverage
+.worktrees/
+.claude/
+.planning/
+.serena/
+docs/superpowers/

synapps_mcp-1.2.0/.synapps/config.json

@@ -0,0 +1,9 @@
+{
+  "project_path": "/Users/alex/Dev/mcpcontext",
+  "container_name": "synapps-mcpcontext",
+  "port": 57481,
+  "last_indexed": null,
+  "experimental": {
+    "http_endpoints": true
+  }
+}

synapps_mcp-1.2.0/.synignore

@@ -0,0 +1,11 @@
+# Tooling and IDE metadata
+.claude/
+.planning/
+.serena/
+
+# Documentation not part of the codebase
+docs/superpowers/
+docs/demo/
+
+# Test fixtures (indexed separately by integration tests)
+tests/fixtures/

synapps_mcp-1.2.0/CHANGELOG.md

@@ -0,0 +1,63 @@
+# Changelog
+
+All notable changes to Synapps will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/), and this project adheres to [Semantic Versioning](https://semver.org/).
+
+## [Unreleased]
+
+## [1.2.0] - 2026-03-28
+
+### Added
+- **PyPI distribution** — install via `pip install synapps-mcp` (package renamed from `synapps` to `synapps-mcp`)
+- **`synapps init` command** — interactive setup wizard that detects project languages, checks prerequisites, indexes the project, and configures MCP clients (Claude Desktop, Claude Code, Cursor, Copilot)
+- **`__version__` attribute** — `synapps.__version__` returns the installed version at runtime via `importlib.metadata`
+- **CI/CD publish workflow** — `.github/workflows/publish.yml` builds, smoke-tests, and publishes to PyPI on `v*` tags via OIDC trusted publishing
+- **Wheel smoke test** — CI verifies `solidlsp` and all 4 tree-sitter grammars are included in the published wheel
+- **Platform-aware doctor fix strings** — every failed check shows exact install commands for macOS (`brew`) or Linux (`apt-get`)
+- **Actionable error messages** — Docker-not-running, Memgraph connection lost, project-not-indexed, and language server timeout errors all show recovery commands
+- **MCP client auto-detection** — `synapps init` finds installed MCP clients and offers to write config with atomic merge (preserves existing server entries)
+
+### Changed
+- Package distribution name changed from `synapps` to `synapps-mcp` (Python import paths unchanged)
+- `synapps doctor` now exits with code 1 when any check fails (enables use in scripts and CI)
+- SYNAPPS logo banner moved from `synapps index` (first run) to `synapps init`
+- Version bumped from 1.0.0 to 1.2.0
+
+### Fixed
+- Language server timeout no longer aborts the entire indexing pass — timed-out files are skipped with a warning naming the file
+
+## [1.1.0] - 2026-03-28
+
+### Added
+- `find_http_endpoints` MCP tool — search endpoints by route pattern, HTTP method, or language
+- `trace_http_dependency` MCP tool — find server handler and all client call sites for an endpoint
+- Route conflict detection — indexer warns when multiple methods serve the same (HTTP method, route) pair
+- JAX-RS annotation support (`@Path`, `@GET`, `@POST`, etc.) in Java server-side extraction
+- README HTTP Endpoint Tracing section with supported frameworks table, tool examples, and known limitations
+
+### Fixed
+- Nested class HTTP call attribution now uses narrowest-range matching instead of last-match across all 4 extractors
+- JAX-RS route constraints (`{param: regex}`) correctly normalized to `{param}` during extraction
+
+### Changed
+- HTTP endpoint extraction now runs by default — no longer requires `experimental.http_endpoints` config flag
+- MCP tool count increased from 19 to 21
+- Removed all "experimental" qualifiers from schema notes, agent instructions, and log messages
+
+## [1.0.0] - 2026-03-26
+
+### Added
+- Multi-language indexing: C#, Python, TypeScript/JavaScript, Java
+- Graph-based code intelligence via Memgraph
+- MCP server with 25+ tools for AI agents
+- CLI with full query and management capabilities
+- Automatic per-project Docker container management
+- Incremental sync via git diff
+- Live file watching with `synapps watch`
+- Interface dispatch resolution in call graph traversal
+- Impact analysis with test coverage detection
+- Token-efficient output format for AI consumption
+- Scoped context retrieval (`structure`, `method`, `edit`)
+- Architectural audit rules
+- Symbol summaries (manual and auto-generated)

synapps_mcp-1.2.0/CLAUDE.md

@@ -0,0 +1,246 @@
+*IMPORTANT*
+- Never assume the user is correct. Trust but verify all statements, using the code as a source of truth. When in doubt, ask the user for clarification.
+- Design all classes and functions with testability in mind. Use Dependency Injection liberally.
+- Keep classes and functions small, clear, and with a singular purpose (SRP).
+- Use comments sparingly. Comments should only exist to clarify a design choice/decision, not to explain what the code is doing. (WHY not WHAT)
+- Make sure all unit and integration tests pass before considering a task complete.
+- Every bugfix must include a regression test that would have caught the bug.
+
+## Synapps MCP
+
+This project is indexed by the Synapps MCP server. Use it instead of grep/read for navigating code relationships:
+
+- Before modifying a method, use `get_context_for` (scope="edit") to understand its callers, callees, dependencies, and test coverage
+- Use `find_callers` / `find_usages` to trace how a symbol is used across the codebase — prefer this over grep
+- Use `find_callees` (with optional `depth` param for reachable call tree) to understand what a method depends on downstream
+- After making changes, use `analyze_change_impact` to verify no unexpected breakage
+- Use `get_hierarchy` to understand inheritance before modifying class structures
+- Use `search_symbols` to find symbols by name, kind, file, or namespace — faster and more precise than file search
+- Use `execute_query` for ad-hoc Cypher queries; call `get_schema` first to see available labels and relationships
+- Use `summary` with action='set'/'get'/'list' to manage symbol summaries
+- Use `find_usages` with `kind` param to filter type references, or `include_test_breakdown=True` for prod/test split
+- CLI-only tools (not available via MCP): `synapps doctor`, `synapps delete <path>`, `synapps status <path>`
+- If any issues with the MCP or inconsistencies in the graph vs filesystem are found, report this to the user as a side note.
+
+## Common Commands
+
+```bash
+# Activate venv (always required before running Python commands)
+source .venv/bin/activate
+
+# Unit tests (no external dependencies, ~1.7s)
+pytest tests/unit/ -v
+
+# Integration tests (requires Memgraph on localhost:7687 and .NET SDK)
+docker compose up -d  # start Memgraph + Memgraph Lab (Lab UI at http://localhost:3000; in-memory — data lost on restart, tests always re-index from scratch)
+pytest tests/integration/test_mcp_tools.py -v -m integration      # MCP tool integration(C#) tests
+pytest tests/integration/test_mcp_tools_typescript.py -v -m integration # Typescript integration tests (MCP)
+pytest tests/integration/test_mcp_tools_python.py -v -m integration # Python integration tests (MCP)
+
+pytest tests/integration/test_cli_commands.py -v -m integration   # CLI command integration tests
+pytest tests/integration/test_cli_commands_python.py -v -m integration   # Python CLI command integration tests
+pytest tests/integration/test_cli_commands_typescript.py -v -m integration   # typescript CLI command integration tests
+```
+
+<!-- GSD:project-start source:PROJECT.md -->
+## Project
+
+**Synapps**
+
+Synapps is a code intelligence MCP server that indexes multi-language codebases (C#, TypeScript, Python, Java) using tree-sitter and Language Server Protocol, stores symbols and relationships in a Memgraph graph database, and exposes semantic query tools (find callers, trace call chains, analyze change impact) for AI coding agents and developers via both MCP and CLI.
+
+**Core Value:** AI coding agents can instantly understand code structure and relationships across an entire codebase without reading every file.
+
+### Constraints
+
+- **Tech stack**: Python 3.11, existing CLI (typer), existing MCP server (FastMCP) — new features must integrate with these
+- **No auto-install**: Report + instructions only — users stay in control of their environment
+- **Platform**: Must work on macOS and Linux at minimum (Docker required for Memgraph)
+<!-- GSD:project-end -->
+
+<!-- GSD:stack-start source:codebase/STACK.md -->
+## Technology Stack
+
+## Languages & Runtime
+- **Python 3.11** — entire application codebase (`src/synapps/`, `src/solidlsp/`)
+- **Cypher** — graph query language used in all `GraphConnection` calls (`src/synapps/graph/`)
+- **C#, TypeScript, Python, Java** — target languages indexed by the tool (not part of the tool's own runtime)
+## Frameworks & Libraries
+| Library | Version | Purpose | Location |
+|---------|---------|---------|----------|
+| `mcp` | >=1.0.0 (installed: 1.26.0) | Model Context Protocol SDK — exposes the MCP server | `src/synapps/mcp/server.py` |
+| `neo4j` | >=5.0.0 (installed: 6.1.0) | Bolt-protocol driver used against Memgraph | `src/synapps/graph/connection.py` |
+| `typer` | >=0.12.0 (installed: 0.24.1) | CLI framework for the `synapps` command | `src/synapps/cli/app.py` |
+| `watchdog` | >=4.0.0 (installed: 6.0.0) | Filesystem event watcher for live re-indexing | `src/synapps/watcher/watcher.py` |
+| `pydantic` | >=2.0.0 | Data validation (declared; minimal direct usage observed) | `pyproject.toml` |
+| `sensai-utils` | >=1.5.0 (installed: 1.6.0) | Pickle cache, string mixins, logging utilities | `src/solidlsp/ls.py`, `src/solidlsp/ls_process.py`, `src/synapps/util/file_system.py` |
+| `overrides` | >=7.7.0 | Runtime enforcement of `@override` decorator | `src/solidlsp/` |
+| `pathspec` | >=0.12.1 | `.gitignore`-style path matching for ignored paths | `src/synapps/util/file_system.py` |
+| `psutil` | >=7.0.0 | Process management for language server subprocesses | `pyproject.toml` |
+| `beautifulsoup4` | >=4.12.0 | HTML parsing in text utilities | `src/synapps/util/text_utils.py` |
+| `joblib` | >=1.3.0 | Parallel execution for batch indexing operations | `src/synapps/util/text_utils.py` |
+| `charset-normalizer` | >=3.0.0 | File encoding detection | `pyproject.toml` |
+| `requests` | >=2.31.0 | HTTP calls (e.g., language server binary downloads) | `pyproject.toml` |
+| `tree-sitter` | >=0.24.0 | Core parsing engine for AST extraction | `src/synapps/indexer/tree_sitter_util.py`, all language plugin indexers |
+| `tree-sitter-c-sharp` | >=0.23.0 | C# grammar for tree-sitter | `src/synapps/indexer/indexer.py`, `src/synapps/plugin/csharp.py` |
+| `tree-sitter-python` | >=0.25.0 | Python grammar for tree-sitter | `src/synapps/plugin/python.py`, `src/synapps/indexer/python/` |
+| `tree-sitter-typescript` | >=0.23.2 | TypeScript/JavaScript grammar for tree-sitter | `src/synapps/plugin/typescript.py`, `src/synapps/indexer/typescript/` |
+| `tree-sitter-java` | >=0.23.0 | Java grammar for tree-sitter | `src/synapps/plugin/java.py` |
+| `docker` | >=7.0.0 | Docker SDK — manages per-project Memgraph containers | `src/synapps/container/manager.py` |
+| `pyright` | >=1.1.0 | Python language server (bundled binary, used by solidlsp) | `src/solidlsp/language_servers/pyright_server.py` |
+| Library | Version | Purpose |
+|---------|---------|---------|
+| `pytest` | >=8.0.0 | Test runner |
+| `pytest-timeout` | >=2.0.0 | Per-test timeouts (default 10s via `pytest.ini`) |
+## Key Dependencies
+## Configuration
+| File | Purpose |
+|------|---------|
+| `pyproject.toml` | Package metadata, all runtime dependencies, dev dependencies, build targets, CLI entry points |
+| `pytest.ini` | Test runner config — 10s timeout, `tests/` path, `src tests/unit` on `pythonpath`, `integration` marker |
+| `docker-compose.yml` | Development convenience — starts a shared Memgraph instance on `localhost:7687` and Memgraph Lab UI on `localhost:3000` |
+| `.synapps/config.json` | Per-project runtime config (created on first run, not checked in) — stores container name and allocated Bolt port |
+| `uv.lock` | Full dependency lockfile |
+| Variable | Purpose |
+|----------|---------|
+| `SYNAPPS_BENCH_LOG` | Optional path to a JSONL file for tool call benchmarking (`src/synapps/mcp/tools.py`) |
+## Build & Dev Tools
+- `synapps` → `synapps.cli:app` (Typer app, `src/synapps/cli/app.py`)
+- `synapps-mcp` → `synapps.mcp.server:main` (MCP server, `src/synapps/mcp/server.py`)
+- `csharp-ls` (Microsoft) — C# indexing
+- `typescript-language-server` + `tsserver` — TypeScript/JavaScript
+- Eclipse JDT LS — Java
+- OmniSharp — alternative C# (experimental)
+<!-- GSD:stack-end -->
+
+<!-- GSD:conventions-start source:CONVENTIONS.md -->
+## Conventions
+
+## Style & Formatting
+- **Indentation:** 4 spaces (Python standard)
+- **Quotes:** Double quotes for strings; single quotes appear occasionally but doubles dominate
+- **Line length:** Not formally enforced (no ruff/black/isort config detected in `pyproject.toml`)
+- **Trailing commas:** Used in multi-line argument lists and collections
+- **`from __future__ import annotations`:** Present in virtually every source file — enables PEP 604 union syntax (`X | Y`) across the entire codebase regardless of Python version
+- **Type hints:** Consistently applied to all function signatures; return types always annotated
+- **No linter config detected:** No `[tool.ruff]`, `[tool.mypy]`, `[tool.black]`, or `.ruff.toml` present. Conventions are maintained by code review, not tooling.
+## Naming Conventions
+| Element | Convention | Example |
+|---------|-----------|---------|
+| Classes | PascalCase | `SynappsService`, `GraphConnection`, `PythonCallExtractor` |
+| Functions (module-level) | snake_case | `upsert_repository`, `compute_sync_diff` |
+| Methods | snake_case | `get_workspace_files`, `index_project` |
+| Private methods/functions | `_snake_case` prefix | `_get_project_roots`, `_rel_path`, `_resolve` |
+| Private module helpers | `_snake_case` prefix | `_p`, `_slim`, `_apply_limit`, `_short_ref` |
+| Constants / module-level literals | `_UPPER_SNAKE` (private) | `_ALWAYS_SKIP`, `_MINIFIED_LINE_THRESHOLD`, `_PYTHON_CALLS_QUERY` |
+| Variables | snake_case | `root_path`, `symbol_map`, `file_extensions` |
+| Type aliases / Literals | PascalCase or `CamelCaseLiteral` | `SymbolKindLiteral`, `AuditRuleLiteral` |
+| Dataclass fields | snake_case | `updated`, `deleted`, `unchanged` |
+| Logger | always named `log` at module level | `log = logging.getLogger(__name__)` |
+| Language-specific extractors | `{Language}{Concept}Extractor` | `PythonCallExtractor`, `CSharpBaseTypeExtractor` |
+| LSP adapters | `{Language}LSPAdapter` | `PythonLSPAdapter`, `TypeScriptLSPAdapter` |
+| Plugin classes | `{Language}Plugin` | `PythonPlugin`, `CSharpPlugin`, `JavaPlugin` |
+## Common Patterns
+## Error Handling
+## Imports & Dependencies
+<!-- GSD:conventions-end -->
+
+<!-- GSD:architecture-start source:ARCHITECTURE.md -->
+## Architecture
+
+## Overview
+## Pattern
+```
+```
+- `ContainerManager` manages a per-project Memgraph Docker container
+- `FileWatcher` provides live re-indexing via filesystem events
+- `LanguageRegistry` + `LanguagePlugin` protocol enables multi-language support
+## Layers & Components
+- Purpose: Accept user commands or AI agent tool calls; delegate to `SynappsService`
+- Location: `src/synapps/cli/app.py`, `src/synapps/mcp/server.py`
+- Depends on: `SynappsService`, `ContainerManager`, `graph.schema`
+- Purpose: Single orchestration point for all indexing, syncing, querying, and watching operations
+- Location: `src/synapps/service.py`
+- Holds: `GraphConnection`, `LanguageRegistry`, active `FileWatcher` instances
+- Depends on: `graph.*`, `indexer.*`, `lsp.*`, `plugin.*`, `watcher.*`
+- Purpose: Provision and manage per-project Memgraph containers via Docker; persist port assignments in `.synapps/config.json`
+- Location: `src/synapps/container/manager.py`
+- Provides: `GraphConnection` to the rest of the system
+- Purpose: Walk project files, extract symbols via `LSPAdapter`, write nodes/edges to graph
+- Location: `src/synapps/indexer/`
+- Sub-components:
+- Purpose: Decouple language-specific extraction from the indexer core; each language provides factory methods for LSP adapter, call extractor, import extractor, type-ref extractor, and attribute extractor
+- Location: `src/synapps/plugin/` (one module per language: `csharp.py`, `python.py`, `typescript.py`, `java.py`)
+- Protocol: `LanguagePlugin` (structural protocol, runtime-checkable) at `src/synapps/plugin/__init__.py`
+- Registry: `LanguageRegistry` in the same file; `default_registry()` registers all four built-in plugins
+- Purpose: Bridge between language server output and the `IndexSymbol` / `LSPAdapter` interface that the indexer consumes
+- Location: `src/synapps/lsp/` — one adapter per language (`csharp.py`, `python.py`, `typescript.py`, `java.py`)
+- Interface: `LSPAdapter` protocol and `IndexSymbol` dataclass at `src/synapps/lsp/interface.py`
+- Backend: Adapters delegate to `solidlsp` (the bundled LSP process manager)
+- Purpose: Launch, manage, and communicate with external language server processes over the LSP protocol (JSON-RPC stdio)
+- Location: `src/solidlsp/`
+- Key files: `ls.py` (base `LanguageServer` ABC), `ls_process.py` (process lifecycle), `lsp_protocol_handler/` (JSON-RPC transport)
+- Language servers: `language_servers/csharp_language_server.py`, `language_servers/pyright_server.py`, `language_servers/typescript_language_server.py`, `language_servers/eclipse_jdtls.py`
+- Purpose: All Cypher query logic; no business logic lives here — pure data access
+- Location: `src/synapps/graph/`
+- Purpose: Expose graph queries as MCP tools callable by AI agents; thin wrappers over `SynappsService`
+- Location: `src/synapps/mcp/tools.py`, `src/synapps/mcp/server.py`, `src/synapps/mcp/instructions.py`
+- Purpose: Watch a project directory for file changes and trigger re-indexing via callback
+- Location: `src/synapps/watcher/watcher.py`
+- Uses: `watchdog` library; debounce logic for rapid file saves
+## Data Flow
+- Persistent graph state lives in Memgraph (in-memory per container restart unless using persistent storage)
+- Per-project config (port, container name) is persisted in `.synapps/config.json`
+- Indexed commit SHA is stored on the `Repository` node in the graph
+## Entry Points
+| Entry Point | Type | Location |
+|-------------|------|----------|
+| `synapps` CLI | CLI (Typer) | `src/synapps/cli/app.py` |
+| `synapps-mcp` MCP server | MCP (stdio) | `src/synapps/mcp/server.py` |
+## Key Abstractions
+- Structural protocol (`@runtime_checkable`) defining the contract for each language
+- Methods: `create_lsp_adapter()`, `create_call_extractor()`, `create_import_extractor()`, `create_base_type_extractor()`, `create_attribute_extractor()`, `create_type_ref_extractor()`, `create_assignment_extractor()`, `parse_file()`
+- Location: `src/synapps/plugin/__init__.py`
+- Implementations: `src/synapps/plugin/csharp.py`, `python.py`, `typescript.py`, `java.py`
+- Interface between language server output and the indexer
+- Methods: `get_workspace_files()`, `get_document_symbols()`, `find_method_calls()`, `find_overridden_method()`
+- Location: `src/synapps/lsp/interface.py`
+- Implementations: `src/synapps/lsp/csharp.py`, `python.py`, `typescript.py`, `java.py`
+- Canonical in-memory representation of a symbol extracted from source
+- Fields: `name`, `full_name`, `kind`, `file_path`, `line`, `end_line`, `signature`, `base_types`, `parent_full_name`
+- Location: `src/synapps/lsp/interface.py`
+- Wraps a `neo4j.Driver` pointed at Memgraph via Bolt
+- Methods: `query()`, `execute()`, `execute_implicit()`, `query_with_timeout()`
+- Location: `src/synapps/graph/connection.py`
+- Facade that owns the `GraphConnection` and `LanguageRegistry`; all public operations go through it
+- Location: `src/synapps/service.py`
+- Nodes: `Repository`, `Directory`, `File`, `Package`, `Class`, `Interface`, `Method`, `Property`, `Field`
+- Edges: `CONTAINS`, `INHERITS`, `IMPLEMENTS`, `DISPATCHES_TO`, `CALLS`, `REFERENCES`, `OVERRIDES`, `IMPORTS`
+- `DISPATCHES_TO` is the traversal-friendly inverse of method-level `IMPLEMENTS`, written at index time to allow interface-crossing path queries without mixed-direction variable-length patterns
+## Error Handling
+- `SynappsService._resolve()` raises `ValueError` for ambiguous short names with a list of candidates
+- `ContainerManager.get_connection()` raises `RuntimeError` if Docker is not available
+- `ContainerManager._wait_for_bolt()` raises `TimeoutError` if Memgraph does not become ready within 30s
+- `GraphConnection.query_with_timeout()` raises `TimeoutError` with a user-friendly message after configurable timeout
+## Cross-Cutting Concerns
+<!-- GSD:architecture-end -->
+
+<!-- GSD:workflow-start source:GSD defaults -->
+## GSD Workflow Enforcement
+
+Before using Edit, Write, or other file-changing tools, start work through a GSD command so planning artifacts and execution context stay in sync.
+
+Use these entry points:
+- `/gsd:quick` for small fixes, doc updates, and ad-hoc tasks
+- `/gsd:debug` for investigation and bug fixing
+- `/gsd:execute-phase` for planned phase work
+
+Do not make direct repo edits outside a GSD workflow unless the user explicitly asks to bypass it.
+<!-- GSD:workflow-end -->
+
+<!-- GSD:profile-start -->
+## Developer Profile
+
+> Profile not yet configured. Run `/gsd:profile-user` to generate your developer profile.
+> This section is managed by `generate-claude-profile` -- do not edit manually.
+<!-- GSD:profile-end -->

synapps_mcp-1.2.0/CONTRIBUTING.md

@@ -0,0 +1,62 @@
+# Contributing to Synapps
+
+Thanks for your interest in contributing! This guide will help you get set up and make your first contribution.
+
+## Development setup
+
+```bash
+# Clone the repo
+git clone https://github.com/SynappsCodeComprehension/synapps.git
+cd synapps
+
+# Create a virtual environment and install
+python -m venv .venv
+source .venv/bin/activate
+pip install -e ".[dev]"
+```
+
+## Running tests
+
+```bash
+# Unit tests (no external dependencies)
+pytest tests/unit/ -v
+
+# Integration tests (requires Docker + Memgraph)
+docker compose up -d
+pytest tests/integration/ -v -m integration
+```
+
+Unit tests should always pass before submitting a PR. Integration tests require Docker and a running Memgraph instance.
+
+## Making changes
+
+1. Fork the repo and create a branch from `main`
+2. Make your changes
+3. Add or update tests for your changes
+4. Run `pytest tests/unit/ -v` and ensure all tests pass
+5. Commit with a clear message describing *why*, not just *what*
+6. Open a pull request against `main`
+
+## Code style
+
+- Python 3.11+ with type annotations on all function signatures
+- Double quotes for strings
+- 4-space indentation
+- `from __future__ import annotations` in every source file
+- Comments explain *why*, not *what* — keep them sparse
+- Classes and functions should be small with a single responsibility
+
+## Project structure
+
+- `src/synapps/` — main application code
+- `src/solidlsp/` — LSP process management library
+- `tests/unit/` — unit tests (no external dependencies)
+- `tests/integration/` — integration tests (require Docker + Memgraph)
+
+## Reporting bugs
+
+Open an issue using the **Bug Report** template. Include reproduction steps, expected vs actual behavior, and your environment details.
+
+## Suggesting features
+
+Open an issue using the **Feature Request** template. Describe the problem you're solving and your proposed approach.

synapps_mcp-1.2.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Alex Smith
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.