Synapse

Project-agnostic MCP server that turns your /docs folder into a shared “brain” for AI agents.

Synapse exposes your project’s documentation as Model Context Protocol (MCP) resources, so any MCP-capable client (e.g. Cursor, Claude Desktop) can use them as stable, up-to-date context. The goal is to reduce hallucinations and keep agents aligned with your project’s vision, conventions, and goals.

Why Synapse?

• Agnostic — Works with any repo. No product-specific logic; you bring the docs, Synapse serves them.

• Convention over config — Put Markdown in /docs at the project root; the server discovers and exposes it.

• OSS — MIT license. You can use, change, and contribute.

Status

Early stage. The repo has the basic TypeScript + MCP SDK setup and a stub entrypoint. Next steps:

1. Implement MCP resources: list and read all .md files under /docs (URIs like synapse://docs/...).

2. Optional config (e.g. custom docs path, handoffs) later.

Requirements

• Node.js ≥ 18

• pnpm (recommended) or npm

Installation

# Clone the repo
git clone https://github.com/gabriel-romero-poza/synapse-mcp.git
cd synapse-mcp

# Install dependencies
pnpm install

# Build
pnpm build

Or use as a dependency in another project:

pnpm add synapse-mcp   # when published to npm
# or from git
pnpm add github:gabriel-romero-poza/synapse-mcp

Usage

Run the server (stdio transport). The project root is the directory from which the MCP client runs the process (e.g. your repo root when Cursor starts Synapse).

pnpm start
# or after npm/pnpm link / global install:
synapse

Environment (optional):

Cursor

1. Settings → Tools & MCP → Add new MCP server

2. Add a server with:

   • Name: synapse (or any name)

   • Type: command

   • Command: node

   • Arguments: path/to/synapse/dist/index.js
     (or pnpm exec synapse if run from the synapse repo / a workspace that has it)

3. Ensure the server is started with cwd = your project root (where /docs lives).

(Exact Cursor UI may vary; refer to Cursor MCP docs.)

Project layout

synapse-mcp/
├── .cursor/rules/    # Cursor rules (commits, TypeScript, agentic workflow)
├── .github/          # PR template, issue templates
├── docs/             # Project vision and design (source of truth)
├── src/
│   └── index.ts      # Entrypoint (MCP server stub)
├── AGENTS.md         # Context for AI agents
├── CONTRIBUTING.md   # Commit conventions, PR process, guardrails
├── package.json
├── tsconfig.json
├── pnpm-lock.yaml
├── README.md
└── LICENSE

Contributing

Contributions are welcome. See CONTRIBUTING.md for commit conventions (Conventional Commits), PR process, and guardrails. Open an issue for bigger changes; use pull requests for patches and small features. Keep the scope agnostic: no product-specific logic inside Synapse; conventions and optional config only.

License

MIT. See LICENSE.