# FullStackVibes MCP server

Exposes the FullStackVibes Handshake retrieval primitive (and adjacent read endpoints) as [Model Context Protocol](https://modelcontextprotocol.io) tools. Drop it into any MCP-aware agent — Claude Desktop, Claude Code, Cursor, Cline, Continue, custom clients — and the agent can pull typed context windows from the FullStackVibes public corpus on demand.

## Tools exposed

| Tool | Purpose |
|---|---|
| `fsv_handshake` | Retrieve a Precision Bundle: typed context windows packed to a character budget, filterable by Space, window type, window tags, pattern tags, and quality. |
| `fsv_list_spaces` | List all Spaces (broad cross-cutting domains: fintech, security, codebase, …). |
| `fsv_get_artifact` | Fetch a single artifact by `contextId` + `slug` — full body, windows, tags, spaces. |
| `fsv_search` | Full-text search across the corpus, optionally filtered by Space. |

## Install

### Option A — local clone

```bash
mkdir -p ~/.fsv-mcp && cd ~/.fsv-mcp
curl -sSL https://fullstackvibes.com/integrations/mcp/server.js > server.js
curl -sSL https://fullstackvibes.com/integrations/mcp/package.json > package.json
npm install
```

### Option B — npm (when published)

```bash
npm install -g fsv-mcp-server
```

## Configure

### Claude Desktop / Claude Code

Edit `~/.config/Claude/claude_desktop_config.json` (or your platform's equivalent):

```json
{
  "mcpServers": {
    "fullstackvibes": {
      "command": "node",
      "args": ["/Users/you/.fsv-mcp/server.js"]
    }
  }
}
```

### Cursor / Cline / Continue / generic stdio MCP

Same shape — point your client at `node /path/to/server.js`. No flags, no env vars required.

## Optional environment

| Variable | Default | Purpose |
|---|---|---|
| `FSV_API_BASE` | `https://api.osenv.io` | Override the API host (useful for self-hosted FSV). |
| `FSV_INCLUDE_OWNER_KEPT` | `false` | If `true`, the default `includeOwnerKept` for `fsv_handshake` flips on. Useful while the corpus is small. |

## Smoke test

Without an MCP client, you can drive the server over stdio:

```bash
echo '{"jsonrpc":"2.0","id":1,"method":"tools/list"}' | node server.js
```

You should see the tool catalogue printed back as JSON.

## Calling fsv_handshake

```jsonc
{
  "spaces":      ["fintech"],
  "windowTypes": ["SCHEMA", "ANTI_PATTERN"],
  "windowTags":  ["drop-in-ready"],
  "patternTags": { "FORM": ["recipe"] },
  "qualityMin":  0.5,
  "maxChars":    6000,
  "includeOwnerKept": true
}
```

Returns a packed bundle: typed windows in `data.windows`, totals + `exhausted` flag in `data`. Each window includes the parent artifact's `publicContextId`, `slug`, `qualityScore`, `spaces`, and the `sourceInferenceRunId` so the bundle is fully provenance-backed.

## License

MIT. The retrieved corpus content carries its own per-artifact license (typically CC BY-SA 4.0); preserve attribution.