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):

Variable	Description
SYNAPSE_PROJECT_ROOT	Override project root (default: process.cwd())

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.