npm package: @rigstate/mcp
Description: Rigstate MCP Server - Model Context Protocol for AI Editors
Author: Rigstate
Latest version: 0.7.14

# Rigstate MCP Server

A [Model Context Protocol](https://modelcontextprotocol.io/) (MCP) server that exposes Rigstate's Project Brain and Council Decisions to AI editors like **Cursor** and **Claude Desktop**.

> ⚠️ **v0.4.0 Update**: MCP is now in **Read-Only Mode**. Write operations are deprecated.
> Use `rigstate check` and `rigstate daemon` CLI commands for rule enforcement and task processing.

## 🚀 Features

### Read Operations (Recommended)
- **`get_project_context`**: Returns the project type, tech stack, and high-level description
- **`query_brain`**: Semantic search against project memories, architecture rules, and constraints
- **`get_latest_decisions`**: Fetches recent ADRs and decisions from The Architect's Council
- **`list_roadmap_tasks`**: Lists all actionable tasks for a project
- **`get_next_roadmap_step`**: Fetches the next logical step from the roadmap
- **`get_learned_instructions`**: Fetch all learned behaviors and corrections

### Write Operations (⚠️ DEPRECATED)
> These tools will be removed in a future version. Use the Rigstate Dashboard or CLI instead.
- **`save_decision`**: Saves architectural decisions to the Project Brain
- **`submit_idea`**: Submits ideas to the Idea Lab
- **`update_roadmap`**: Updates roadmap step status

### CLI Commands (Recommended for Rule Enforcement)
Use the `@rigstate/cli` package for local rule enforcement:
- `rigstate check` - Validate code against Guardian rules
- `rigstate daemon` - Continuous file monitoring with rule validation
- `rigstate hooks install` - Install pre-commit hooks

## 📦 Installation

```bash
npm install @rigstate/mcp
```

Or use directly with npx:

```bash
RIGSTATE_API_KEY=sk_rigstate_xxx npx @rigstate/mcp
```

## 🔑 Authentication

The MCP server requires a Rigstate API key. Get yours from:

👉 https://rigstate.dev/settings/api-keys

Set it as an environment variable:

```bash
export RIGSTATE_API_KEY=sk_rigstate_xxxxxxxxxxxxxxxx
```

## ⚙️ Configuration

### Cursor

Add to your `.cursor/mcp.json`:

```json
{
  "mcpServers": {
    "rigstate": {
      "command": "npx",
      "args": ["@rigstate/mcp"],
      "env": {
        "RIGSTATE_API_KEY": "sk_rigstate_xxx"
      }
    }
  }
}
```

### Claude Desktop

Add to your Claude Desktop config (`~/Library/Application Support/Claude/claude_desktop_config.json` on macOS):

```json
{
  "mcpServers": {
    "rigstate": {
      "command": "npx",
      "args": ["@rigstate/mcp"],
      "env": {
        "RIGSTATE_API_KEY": "sk_rigstate_xxx"
      }
    }
  }
}
```

## 🔧 Environment Variables

| Variable | Required | Description |
|----------|----------|-------------|
| `RIGSTATE_API_KEY` | ✅ | Your Rigstate API key (sk_rigstate_...) |
| `RIGSTATE_SUPABASE_URL` | ❌ | Override Supabase URL (defaults to production) |
| `RIGSTATE_SUPABASE_ANON_KEY` | ❌ | Override Supabase anon key (defaults to production) |

## 🛠️ Available Tools

### `get_project_context`

Returns project metadata and tech stack information.

**Input:**
```json
{
  "projectId": "uuid-of-your-project"
}
```

**Output:**
```
Project Type: WEB
Framework: Next.js 14.1.0
ORM: Prisma 5.0.0
Key Libraries: Tailwind, Supabase, Zod
Top Folders: src, public, prisma

Description: A SaaS dashboard for...
```

### `query_brain`

Searches the Project Brain for relevant memories.

**Input:**
```json
{
  "projectId": "uuid-of-your-project",
  "query": "authentication flow",
  "limit": 5
}
```

**Output:**
```
=== PROJECT BRAIN: RELEVANT MEMORIES ===
Query: "authentication flow"
Found 3 relevant memories:

- [ARCHITECTURE] [auth, security]: Use Supabase Auth with RLS for all protected routes
- [DECISION]: Implement magic link login instead of password-based auth
- [CONSTRAINT]: All API routes must verify JWT before processing

==========================================
```

### `get_latest_decisions`

Fetches recent council sessions and decisions.

**Input:**
```json
{
  "projectId": "uuid-of-your-project",
  "limit": 3
}
```

**Output:**
```
=== CURRENT FOCUS ===
Step 3: Implement Dashboard Views
Focus: Frontend Development

=== RECENT COUNCIL SESSIONS (2) ===

📅 Session on 1/3/2026
   Agents: product-owner, cto, security-auditor
   Key Feedback:
   🕵️ The Product Owner: ✅
      - Feature scope is well-defined
   🔧 CTO: ✅
      - Dependencies are properly ordered

=== KEY DECISIONS FROM BRAIN ===
- [ARCHITECTURE] Use server components by default
- [DECISION] Implement optimistic updates for better UX
```

---

## ✏️ Write Operations (v0.2.0+)

### `save_decision`

Saves a new architectural decision (ADR) to the Project Brain.

**Input:**
```json
{
  "projectId": "uuid-of-your-project",
  "title": "Use Prisma for ORM",
  "decision": "We will use Prisma as our ORM for type-safe database access.",
  "rationale": "Prisma provides excellent TypeScript integration and migration tooling.",
  "category": "architecture",
  "tags": ["database", "prisma"]
}
```

**Output:**
```
✅ Decision "Use Prisma for ORM" saved to project "My App" with importance 9/10
```

### `submit_idea`

Submits a new idea to the Idea Lab for review.

**Input:**
```json
{
  "projectId": "uuid-of-your-project",
  "title": "Add dark mode toggle",
  "description": "Allow users to switch between light and dark themes.",
  "category": "feature",
  "tags": ["ui", "accessibility"]
}
```

**Output:**
```
💡 Idea "Add dark mode toggle" submitted to Idea Lab for project "My App". Status: Draft (awaiting review)
```

### `update_roadmap`

Updates the status of a roadmap step.

**Input (by ID):**
```json
{
  "projectId": "uuid-of-your-project",
  "chunkId": "uuid-of-roadmap-chunk",
  "status": "COMPLETED"
}
```

**Input (by title):**
```json
{
  "projectId": "uuid-of-your-project",
  "title": "Implement auth",
  "status": "ACTIVE"
}
```

**Output:**
```
✅ Roadmap step "Implement Authentication" updated: LOCKED → ACTIVE
```

### `run_architecture_audit`

Audits code against project rules and security patterns.

**Input:**
```json
{
  "projectId": "uuid-of-your-project",
  "filePath": "src/app/api/users/route.ts",
  "content": "export async function GET(req) { ... }"
}
```

**Output (Pass):**
```
✅ PASSED - No violations found in src/app/api/users/route.ts
Score: 100/100
```

**Output (Fail):**
```
⚠️ AUDIT FAILED - 2 violation(s) found in src/app/api/users/route.ts
Score: 65/100
• HIGH: 1
• MEDIUM: 1
• LOW: 0

Violations:
1. [HIGH] Potential XSS Vulnerability (line 15)
   Using dangerouslySetInnerHTML can expose your app to XSS attacks.
   → Sanitize HTML content using a library like DOMPurify before rendering.

2. [MEDIUM] Potentially Missing Authentication
   API route handler may not be checking authentication.
   → Add authentication check at the start of your API handler.

### `sync_ide_rules`

Generates the appropriate rules file content (e.g. `.cursorrules`, `.windsurfrules`) based on project context and user settings.

**Input:**
```json
{
  "projectId": "uuid-of-your-project"
}
```

**Output:**
```markdown
FileName: .cursorrules

Content:
RIGSTATE_START
## 🤖 THE ACTIVE TEAM
...
RIGSTATE_END
```

### `check_rules_sync`

Verifies if the IDE rules are present and belong to the correct project.

**Input:**
```json
{
  "projectId": "uuid-of-your-project",
  "currentRulesContent": "full content of your .cursorrules file"
}
```

## 🤖 Strict Tool Ownership (v0.3.0+)
Rigstate MCP enforces **Strict Tool Ownership**. In your generated rules, every tool is explicitly bound to an Agent ID. When an AI invokes a tool, it is instructed to adopt the persona and authority level of the owner.

## 🔒 Security

- The server only accesses data belonging to projects owned by the API key holder
- All database queries include ownership verification (`owner_id = userId`)
- API key usage is tracked via `last_used_at` timestamp

## 📝 Development

```bash
# Install dependencies
npm install

# Build
npm run build

# Development mode (with watch)
npm run dev

# Test locally
RIGSTATE_API_KEY=sk_rigstate_xxx node dist/index.js
```

## 📄 License

MIT