# 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](https://modelcontextprotocol.io/) (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

```bash
# 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:

```bash
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).

```bash
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](https://docs.cursor.com/context/model-context-protocol).)*

---

## 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](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](LICENSE).