Rigstate MCP Server

A Model Context Protocol (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

npm install @rigstate/mcp

Or use directly with npx:

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:

export RIGSTATE_API_KEY=sk_rigstate_xxxxxxxxxxxxxxxx

⚙️ Configuration

Cursor

Add to your .cursor/mcp.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):

{
  "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:

{
  "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:

{
  "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:

{
  "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:

{
  "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:

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

{
  "projectId": "uuid-of-your-project",
  "chunkId": "uuid-of-roadmap-chunk",
  "status": "COMPLETED"
}

Input (by title):

{
  "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:

{
  "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:

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:

{
  "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

# 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