rivets-mcp

MCP (Model Context Protocol) server for the Rivets issue tracking system. Enables AI assistants like Claude to manage issues directly through a standardized protocol.

Features

• 10 MCP tools for complete issue management
• Multi-workspace support - work with multiple projects in one session
• Stdio transport - works with any MCP-compatible client
• Structured tracing - debug with RUST_LOG=debug

Installation

From source

cargo install --path crates/rivets-mcp

Build locally

cargo build --release -p rivets-mcp

Binary will be at target/release/rivets-mcp.

Usage

With Claude Code

Add to your Claude Code MCP configuration (~/.config/claude-code/mcp.json or project .claude/mcp.json):

{
  "mcpServers": {
    "rivets": {
      "command": "rivets-mcp",
      "args": []
    }
  }
}

Or with an absolute path:

{
  "mcpServers": {
    "rivets": {
      "command": "/path/to/rivets-mcp",
      "args": []
    }
  }
}

Manual testing

# Run the server (communicates via stdin/stdout)
rivets-mcp

# With debug logging (logs go to stderr)
RUST_LOG=debug rivets-mcp

Available Tools

Context Management

Query Tools

Modification Tools

Tool Parameters

set_context

{
  "workspace_root": "/path/to/your/project"
}

list

{
  "status": "open",           // optional: open, in_progress, blocked, closed
  "priority": 1,              // optional: 0-4
  "issue_type": "bug",        // optional: bug, feature, task, epic, chore
  "assignee": "alice",        // optional
  "label": "urgent",          // optional
  "limit": 20,                // optional, default 100
  "workspace_root": "/path"   // optional, uses current context if omitted
}

create

{
  "title": "Fix login bug",           // required
  "description": "Users can't...",    // optional
  "priority": 1,                      // optional, default 2
  "issue_type": "bug",                // optional, default "task"
  "assignee": "bob",                  // optional
  "labels": ["urgent", "auth"],       // optional
  "design": "## Approach\n...",       // optional
  "acceptance_criteria": "- [ ] Tests pass",   // optional
  "workspace_root": "/path"           // optional
}

update

{
  "issue_id": "rivets-abc",           // required
  "title": "New title",               // optional
  "status": "in_progress",            // optional
  "priority": 0,                      // optional
  "assignee": "",                     // optional, empty string clears
  "workspace_root": "/path"           // optional
}

dep

{
  "issue_id": "rivets-abc",           // required: the blocked issue
  "depends_on_id": "rivets-xyz",      // required: the blocker
  "dep_type": "blocks",               // optional: blocks, related, parent-child, discovered-from
  "workspace_root": "/path"           // optional
}

Workspace Parameter

Most tools accept an optional workspace_root parameter. This enables:

• Multi-workspace workflows: Switch between projects without calling set_context
• Explicit targeting: Specify exactly which project to query/modify
• Fallback behavior: If omitted, uses the current context set via set_context

Debugging

Enable debug logging:

RUST_LOG=debug rivets-mcp

Log levels:

• error - Only errors
• warn - Warnings and errors
• info - Server start/stop (default)
• debug - Tool calls and operations
• trace - Detailed internal operations

Logs are written to stderr (stdout is reserved for MCP protocol).

Example Workflow

1. Set context to your project:

   set_context(workspace_root: "/home/user/myproject")
   

2. Find ready work:

   ready(limit: 5, priority: 1)
   

3. Claim a task:

   update(issue_id: "rivets-abc", status: "in_progress", assignee: "me")
   

4. Complete the task:

   close(issue_id: "rivets-abc", reason: "Implemented in PR #42")
   

Requirements

• A .rivets/ directory in your project (created by rivets init)
• Issues stored in .rivets/issues.jsonl

License

Apache-2.0 (same as rivets)