# solveaux-mcp

> **Give your AI coding agents a permanent memory of your architecture.**

`solveaux-mcp` is the official Model Context Protocol (MCP) bridge for [Solveaux](https://solveaux.com) — an engineering intelligence platform where teams capture architecture decisions (ADRs), research spikes, and team knowledge.

Built on the open [Model Context Protocol (MCP)](https://modelcontextprotocol.io) standard, **any MCP-compliant AI agent, IDE, or autonomous framework can connect** — including Cursor, Claude Desktop, Windsurf, Continue.dev, Zed, GitHub Copilot, and custom agent pipelines.

Once connected, your AI agents can:

- **Read** your team's accepted architecture decisions before generating or refactoring code
- **Read** project constraints, rejected alternatives, and engineering rules
- **Store** new decisions directly back into your Solveaux workspace
- **Stay aligned** with your product's technical direction automatically across all team members and agents

No more AI agents hallucinating architecture violations. No more copy-pasting context into every prompt.

---

## Quick Setup

### 1. Create an Account & Get Your API Key

Solveaux workspaces are strictly private and isolated to protect your engineering decisions and proprietary architecture. To communicate with Solveaux via MCP:

1. **Log in or create an account** at [solveaux.com/login](https://solveaux.com/login). Solveaux is currently **free during the Early Access phase** (terms and conditions apply).
2. Create or open your project in your dashboard.
3. Go to **Project Settings** → copy your project API key (`slvx_proj_...`).

> [!NOTE]
> **Authentication Required**: Because your architecture data is private, the MCP bridge cannot function without a valid API key from an authenticated Solveaux account.

---

### 2. Connect your AI Agent or Editor

`solveaux-mcp` connects via standard MCP stdio. Below are configurations for popular editors and clients:

#### ⚡ Cursor
Add to `.cursor/mcp.json` in your project root or `~/.cursor/mcp.json`:

```json
{
  "mcpServers": {
    "solveaux": {
      "command": "npx",
      "args": ["-y", "solveaux-mcp"],
      "env": {
        "SOLVEAUX_API_KEY": "slvx_proj_your_key_here"
      }
    }
  }
}
```

####  Claude Desktop
Add to your Claude Desktop configuration (`~/Library/Application Support/Claude/claude_desktop_config.json` on macOS or `%APPDATA%\Claude\claude_desktop_config.json` on Windows):

```json
{
  "mcpServers": {
    "solveaux": {
      "command": "npx",
      "args": ["-y", "solveaux-mcp"],
      "env": {
        "SOLVEAUX_API_KEY": "slvx_proj_your_key_here"
      }
    }
  }
}
```

#### 🌊 Windsurf (Codeium)
Add to your Windsurf MCP configuration (`~/.codeium/windsurf/mcp_config.json`):

```json
{
  "mcpServers": {
    "solveaux": {
      "command": "npx",
      "args": ["-y", "solveaux-mcp"],
      "env": {
        "SOLVEAUX_API_KEY": "slvx_proj_your_key_here"
      }
    }
  }
}
```

#### 🔄 Continue.dev (VS Code / JetBrains)
Add to your `~/.continue/config.json`:

```json
{
  "experimental": {
    "modelContextProtocolServers": [
      {
        "transport": {
          "type": "stdio",
          "command": "npx",
          "args": ["-y", "solveaux-mcp"],
          "env": {
            "SOLVEAUX_API_KEY": "slvx_proj_your_key_here"
          }
        }
      }
    ]
  }
}
```

#### ⚡ Zed Editor
Add to `settings.json` in Zed:

```json
{
  "context_servers": {
    "solveaux": {
      "command": "npx",
      "args": ["-y", "solveaux-mcp"],
      "env": {
        "SOLVEAUX_API_KEY": "slvx_proj_your_key_here"
      }
    }
  }
}
```

#### 🌐 Universal / Any MCP-Compatible Client
Any client or CLI that supports the Model Context Protocol stdio transport can use this generic configuration:

```json
{
  "command": "npx",
  "args": ["-y", "solveaux-mcp"],
  "env": {
    "SOLVEAUX_API_KEY": "slvx_proj_your_key_here"
  }
}
```

Restart your client and your AI agent will automatically detect and load all Solveaux tools.

---

## Environment Variables

| Variable | Required | Description |
|---|---|---|
| `SOLVEAUX_API_KEY` | Yes | Project API key from Solveaux Settings (`slvx_proj_...`) |
| `SOLVEAUX_PROJECT_ID` | Optional | Only needed if using an organization-level key |
| `SOLVEAUX_BASE_URL` | Optional | Default: `https://solveaux.com`. Use `http://localhost:3000` for local dev |

---

## What your AI agent can do

Once connected, your agent has access to these MCP tools:

| Tool | What it does |
|---|---|
| `get_project_context` | Returns all accepted ADRs, constraints, rejected options, and team rules for the active project |
| `search_decisions` | Searches decisions and research by keyword |
| `get_file_context` | Returns all decisions that govern a specific source file path |
| `record_decision` | Stores a new architectural decision record directly into Solveaux |
| `record_research` | Stores a technical research spike or benchmark result |
| `get_agent_permissions` | Checks current agent role (Architect, Contributor, or Auditor) |

### Example agent prompts that now work automatically

```
"Before modifying the database layer, check what architecture decisions apply."
-> Agent calls get_file_context("src/lib/db.ts") before writing any code

"We've decided to use tRPC instead of REST for internal APIs. Record this."
-> Agent calls record_decision({title: "Switch to tRPC for internal APIs", ...})

"Has the team evaluated Kafka for the event queue?"
-> Agent calls search_decisions("Kafka") and returns past research or rejections
```

---

## How it works

This package is a **zero-dependency stdio bridge** — it forwards MCP JSON-RPC 2.0 messages from your AI agent to the Solveaux API and returns structured responses.

```
Any AI Agent / IDE / Client
(Cursor, Claude Desktop, Windsurf, Continue, Zed, Copilot, Custom Agents)
        |  MCP JSON-RPC 2.0 over stdio
        v
  solveaux-mcp (this package)
        |  HTTPS POST  x-api-key: slvx_proj_...
        v
  solveaux.com/api/mcp
        |
        v
  Your private Solveaux workspace
  (ADRs, research, constraints — scoped to your project)
```

Your API key is project-scoped — the agent can only read and write to the specific project it's connected to. Other organizations and projects are completely isolated.

Your architecture decisions and team data stay in your private Solveaux workspace. Nothing is stored or logged by this bridge.

---

## 🤖 Connecting Other Agents & Custom Frameworks

Because `solveaux-mcp` strictly implements the official [Model Context Protocol (MCP)](https://modelcontextprotocol.io) specification via standard I/O (stdio), **any autonomous agent, CLI tool, or custom LLM pipeline can connect to Solveaux**.

### Python MCP SDK (LangChain, AutoGen, CrewAI, Custom Scripts)

If you are building your own agent in Python using the official `mcp` SDK:

```python
import asyncio
from mcp import ClientSession, StdioServerParameters
from mcp.client.stdio import stdio_client

async def run():
    server_params = StdioServerParameters(
        command="npx",
        args=["-y", "solveaux-mcp"],
        env={"SOLVEAUX_API_KEY": "slvx_proj_your_key_here"}
    )

    async with stdio_client(server_params) as (read, write):
        async with ClientSession(read, write) as session:
            await session.initialize()

            # Retrieve active architecture decisions & constraints
            context = await session.call_tool("get_project_context", {})
            print("Solveaux Architecture Context:", context)

asyncio.run(run())
```

### TypeScript / Node.js MCP SDK

If you are using `@modelcontextprotocol/sdk`:

```typescript
import { Client } from "@modelcontextprotocol/sdk/client/index.js";
import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js";

const transport = new StdioClientTransport({
  command: "npx",
  args: ["-y", "solveaux-mcp"],
  env: {
    SOLVEAUX_API_KEY: "slvx_proj_your_key_here",
  },
});

const client = new Client(
  { name: "my-custom-agent", version: "1.0.0" },
  { capabilities: {} }
);

await client.connect(transport);

// Fetch project context before the agent writes code
const context = await client.callTool({
  name: "get_project_context",
  arguments: {},
});
console.log(context);
```

### Direct Subprocess / Shell Execution
Any agent loop that spawns processes can run `solveaux-mcp` directly and exchange JSON-RPC lines over stdin/stdout:
```bash
SOLVEAUX_API_KEY=slvx_proj_your_key npx -y solveaux-mcp
```

---

## Syncing decisions from your codebase

Solveaux supports the open `.solveaux` file format — a git-native Markdown protocol for capturing decisions directly in your repo.

Place a `project.solveaux` file at your repo root and your AI agent writes to it automatically. Sync it to Solveaux in one curl:

```bash
curl -X POST "https://solveaux.com/api/organizations/{ORG_ID}/projects/{PROJECT_ID}/sync" \
  -H "x-api-key: slvx_proj_your_key" \
  -H "Content-Type: text/plain" \
  --data-binary "@project.solveaux"
```

Or set up a GitHub Action to auto-sync on every push to `main`:

```yaml
# .github/workflows/solveaux-sync.yml
name: Sync Architecture Decisions

on:
  push:
    branches: [main]
    paths: ['project.solveaux']

jobs:
  sync:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Sync to Solveaux
        run: |
          curl -X POST "https://solveaux.com/api/organizations/${{ secrets.SOLVEAUX_ORG_ID }}/projects/${{ secrets.SOLVEAUX_PROJECT_ID }}/sync" \
            -H "x-api-key: ${{ secrets.SOLVEAUX_API_KEY }}" \
            -H "Content-Type: text/plain" \
            --data-binary "@project.solveaux"
```

---

## Making your AI agent record decisions automatically

Add this to `.cursorrules` (or `CLAUDE.md` / `AGENTS.md`):

```markdown
## Architecture Decision Protocol

Whenever you make a non-trivial architectural choice, add a new library,
or resolve a significant technical trade-off, use the `record_decision`
MCP tool to store it in Solveaux before proceeding.

Include: what was decided, what was rejected and why, and what the
consequences are for future code in this project.
```

Now your agent records decisions automatically — without you having to ask.

---

## Running locally

If you're developing against a local Solveaux instance:

```bash
SOLVEAUX_BASE_URL=http://localhost:3000 SOLVEAUX_API_KEY=slvx_proj_... npx solveaux-mcp
```

---

## Privacy, Early Access & Terms

- **Private & Protected Workspaces:** Solveaux is built for private engineering teams. Your architecture records, decision history, constraints, and research spikes remain strictly private to your authenticated workspace.
- **Free During Early Access:** Solveaux is currently completely free to use during our public Early Access period. Anyone can create an account, create projects, and connect an unlimited number of AI agents.
- **Terms & Future Premium Plans:** Use of Solveaux is governed by our [Terms of Service](https://solveaux.com/terms) and [Privacy Policy](https://solveaux.com/privacy). As we introduce advanced team collaboration features, enterprise security/SSO, and expanded agent quotas, optional premium subscription plans will be introduced.

---

## Requirements

- Node.js 18+
- An active Solveaux account (free during Early Access) at [solveaux.com/login](https://solveaux.com/login)

No other dependencies. The bridge uses only Node.js built-ins.

---

## License

MIT (c) Solveaux

---

## Links

- Platform: https://solveaux.com
- MCP Setup Guide: https://solveaux.com/mcp-server
- ADR Tool: https://solveaux.com/adr-tool
- Why Solveaux: https://solveaux.com/why