Skillintermediate

Sudocode MCP Server Specification

The Sudocode MCP will be a local MCP server that exposes Sudocode CLI functionality to AI agents via the Model Context Protocol, enabling agentic management of specs, issues, and the feedback system.

Claude Code Knowledge Pack7/10/2026

Overview

Sudocode MCP Server Specification

The Sudocode MCP will be a local MCP server that exposes Sudocode CLI functionality to AI agents via the Model Context Protocol, enabling agentic management of specs, issues, and the feedback system.

Overview

Sudocode MCP provides tools for:

Spec Management: Creating and managing specifications with markdown support
Issue Management: Full CRUD operations for bugs, features, tasks, epics, and chores
Relationship Management: Creating links between specs and issues (blocks, implements, etc.)
Feedback System: Anchored feedback from issues to specs with smart relocation
Analytics: Ready work, blocked items, and project statistics

Architecture

Technology Stack

Runtime: Node.js with TypeScript
MCP Framework: @modelcontextprotocol/sdk or fastmcp (if available for Node.js)
CLI Integration: Spawn sudocode CLI commands (similar to beads-mcp approach)
Working Directory: Use SUDOCODE_WORKING_DIR env var or process.cwd()

Design Principles

CLI-First: MCP server wraps existing CLI commands rather than duplicating logic
JSON Output: Always use --json flag for structured, parseable responses
Error Handling: Parse and return meaningful error messages from CLI
Context Preservation: Maintain working directory across tool calls
Database Auto-Discovery: Leverage CLI's built-in .sudocode discovery

Resources

1. `sudocode://quickstart`

Name: "Sudocode Quickstart Guide" Description: Introduction to Sudocode workflow and best practices for agents

Content:

# Sudocode Quickstart

Sudocode is a git-native spec and issue management system designed for AI-assisted development.

## Core Concepts

**Specs**: Technical specifications stored as markdown files
- Types: architecture, api, database, feature, research
- Status: draft → review → approved → deprecated
- Each spec has a unique ID (e.g., sudocode-spec-1) and file path

**Issues**: Work items tracked in the database
- Types: bug, feature, task, epic, chore
- Status: open → in_progress → blocked → closed
- Can reference and implement specs

**Feedback**: Issues can provide anchored feedback on specs
- Anchors track specific lines/sections in spec markdown
- Auto-relocates when specs change (smart anchoring)
- Types: comment, suggestion, request

## Typical Workflow

1. **Check ready work**: `ready` tool to find tasks with no blockers
2. **Claim work**: `update_issue` with status=in_progress
3. **Review specs**: `show_spec` to understand requirements
4. **Provide feedback**: `add_feedback` when specs are unclear
5. **Complete work**: `close_issue` when done
6. **Link entities**: Use `link` to create relationships

## Relationship Types
- `blocks`: Hard blocker (to_id must complete before from_id)
- `implements`: Issue implements a spec
- `references`: Soft reference
- `depends-on`: General dependency
- `parent-child`: Epic/subtask hierarchy
- `discovered-from`: New work found during implementation

2. `sudocode://workflow`

Name: "Agent Workflow Guide" Description: Step-by-step workflow patterns for AI agents

Tools

Issue Management

1. `ready`

Description: Find issues and specs ready to work on (no blockers)

Parameters:

limit (number, default: 10): Max items to return
priority (number?, 0-4): Filter by priority (0=highest)
assignee (string?): Filter by assignee
show_specs (boolean, default: false): Include ready specs
show_issues (boolean, default: true): Include ready issues

Returns: { specs?: Spec[], issues?: Issue[] }

CLI Command: sudocode ready --json [--limit N] [--priority P] [--assignee A] [--specs] [--issues]

Considerations: Make sure the returned issue doesn't overflow context.

2. `list_issues`

Description: List all issues with optional filters

Parameters:

status (IssueStatus?): Filter by status (open, in_progress, blocked, needs_review, closed)
type (IssueType?): Filter by type (bug, feature, task, epic, chore)
priority (number?): Filter by priority (0-4)
assignee (string?): Filter by assignee
limit (number, default: 50): Max results

Returns: Issue[]

CLI Command: sudocode issue list --json [filters]

Considerations: This may produce too much context. The MCP server needs a way of reducing the total context (maybe just name/description) if the total context is too large.

3. `show_issue`

Description: Show detailed issue information including relationships and feedback

Parameters:

issue_id (string, required): Issue ID (e.g., "sudocode-1")

Returns: IssueDetail (includes relationships, tags, feedback provided)

CLI Command: sudocode issue show <id> --json

4. `create_issue`

Description: Create a new issue

Parameters:

title (string, required): Issue title
description (string, default: ""): Description
type (IssueType, default: "task"): Issue type
priority (number, default: 2): Priority 0-4
assignee (string?): Assignee username
parent (string?): Parent issue ID
tags (string[]?): Tags
estimate (number?): Estimated minutes

Returns: Issue

CLI Command: sudocode issue create "<title>" --json [options]

5. `update_issue`

Description: Update an existing issue

Parameters:

issue_id (string, required): Issue ID
status (IssueStatus?): New status
priority (number?): New priority
assignee (string?): New assignee
type (IssueType?): New type
title (string?): New title
description (string?): New description

Returns: Issue

CLI Command: sudocode issue update <id> --json [options]

6. `close_issue`

Description: Close one or more issues

Parameters:

issue_ids (string[], required): Issue IDs to close
reason (string, default: "Completed"): Reason for closing

Returns: CloseResult[] (array of { id, success, error? })

CLI Command: sudocode issue close <ids...> --json [--reason]

7. `blocked_issues`

Description: Get blocked issues showing what's blocking them

Parameters:

show_specs (boolean, default: false): Include blocked specs
show_issues (boolean, default: true): Include blocked issues

Returns: { specs?: BlockedSpec[], issues?: BlockedIssue[] }

CLI Command: sudocode blocked --json [--specs] [--issues]

Spec Management

8. `list_specs`

Description: List all specs with optional filters

Parameters:

status (SpecStatus?): Filter by status (draft, review, approved, deprecated)
type (SpecType?): Filter by type (architecture, api, database, feature, research)
priority (number?): Filter by priority
limit (number, default: 50): Max results

Returns: Spec[]

CLI Command: sudocode spec list --json [filters]

9. `show_spec`

Description: Show detailed spec information including relationships and feedback received

Parameters:

spec_id (string, required): Spec ID (e.g., "sudocode-spec-1")

Returns: SpecDetail (includes relationships, tags, feedback received)

CLI Command: sudocode spec show <id> --json

10. `create_spec`

Description: Create a new spec with markdown file

Parameters:

title (string, required): Spec title
type (SpecType, default: "feature"): Spec type
priority (number, default: 2): Priority 0-4
description (string?): Description
design (string?): Design notes (markdown content)
file_path (string?): Custom file path (default: specs/{id}.md)
parent (string?): Parent spec ID
tags (string[]?): Tags

Returns: Spec

CLI Command: sudocode spec create "<title>" --json [options]

Relationship Management

11. `link`

Description: Create a relationship between two entities

Parameters:

from_id (string, required): Source entity ID
to_id (string, required): Target entity ID
type (RelationshipType, default: "references"): Relationship type
- blocks: Hard blocker
- implements: Issue implements spec
- references: Soft reference
- depends-on: General dependency
- parent-child: Hierarchical
- discovered-from: Found during work
- related: Related entities

Returns: { from, to, type, success }

CLI Command: sudocode link <from> <to> --json [--type]

Feedback System

12. `add_feedback`

Description: Add anchored feedback to a spec from an issue

Parameters:

issue_id (string, required): Issue providing feedback
spec_id (string, required): Spec receiving feedback
content (string, required): Feedback content
type (FeedbackType, default: "comment"): Feedback type
- comment, suggestion, request
line (number?): Line number in spec (exclusive with text)
text (string?): Text to search for anchor (exclusive with line)
agent (string?): Agent name (default: USER env var)

Returns: Feedback

CLI Command: sudocode feedback add <issue-id> <spec-id> --json --content "<text>" [options]

Notes: Either line or text must be provided to create an anchor

13. `list_feedback`

Description: List feedback with filters

Parameters:

issue_id (string?): Filter by issue
spec_id (string?): Filter by spec
type (FeedbackType?): Filter by feedback type
status (FeedbackStatus?): Filter by status (open, acknowledged, resolved, wont_fix)
limit (number, default: 50): Max results

Returns: Feedback[]

CLI Command: sudocode feedback list --json [filters]

14. `show_feedback`

Description: Show detailed feedback including anchor status

Parameters:

feedback_id (string, required): Feedback ID

Returns: FeedbackDetail (includes parsed anchor with location info)

CLI Command: sudocode feedback show <id> --json

15. `acknowledge_feedback`

Description: Acknowledge feedback (status → acknowledged)

Parameters:

feedback_id (string, required): Feedback ID

Returns: Feedback

CLI Command: sudocode feedback acknowledge <id> --json

16. `resolve_feedback`

Description: Mark feedback as resolved

Parameters:

feedback_id (string, required): Feedback ID
comment (string?): Resolution comment

Returns: Feedback

CLI Command: sudocode feedback resolve <id> --json [--comment]

17. `wontfix_feedback`

Description: Mark feedback as won't fix

Parameters:

feedback_id (string, required): Feedback ID
reason (string?): Reason for not fixing

Returns: Feedback

CLI Command: sudocode feedback wont-fix <id> --json [--reason]

18. `stale_feedback`

Description: List feedback with stale anchors (spec changed, anchor lost)

Parameters: None

Returns: Feedback[] (filtered to anchor_status === 'stale')

CLI Command: sudocode feedback stale --json

19. `relocate_feedback`

Description: Manually relocate a stale feedback anchor

Parameters:

feedback_id (string, required): Feedback ID
line (number, required): New line number in spec

Returns: Feedback

CLI Command: sudocode feedback relocate <id> --json --line <number>

Analytics

20. `stats`

Description: Get comprehensive project statistics

Parameters: None

Returns:

{
  specs: {
    total: number,
    by_status: Record<SpecStatus, number>,
    by_type: Record<SpecType, number>,
    ready: number
  },
  issues: {
    total: number,
    by_status: Record<IssueStatus, number>,
    by_type: Record<IssueType, number>,
    ready: number,
    blocked: number
  },
  relationships: {
    total: number,
    by_type: Record<RelationshipType, number>
  },
  recent_activity: {
    specs_updated: number,
    issues_updated: number,
    issues_created: number,
    issues_closed: number
  }
}

CLI Command: sudocode stats --json

21. `status`

Description: Get quick project status summary

Parameters:

verbose (boolean, default: false): Show detailed status

Returns: Simplified version of stats

CLI Command: sudocode status --json [--verbose]

Initialization

22. `init`

Description: Initialize sudocode in current directory

Returns: { success: boolean, path: string }

CLI Command: sudocode init

Implementation Notes

CLI Client Architecture

class SudocodeClient {
  private workingDir: string;
  private cliPath: string;

  constructor(config?: {
    workingDir?: string;
    cliPath?: string;
    dbPath?: string;
  });

  private async exec(
    command: string[],
    options?: { json?: boolean }
  ): Promise<any>;

  // Implement tool methods that call this.exec()
  async ready(params: ReadyParams): Promise;
  async listIssues(params: ListIssuesParams): Promise<Issue[]>;
  // ... etc
}

Environment Variables

SUDOCODE_PATH: Path to sudocode CLI (default: auto-discover from PATH)
SUDOCODE_DB: Path to database file (default: auto-discover)
SUDOCODE_WORKING_DIR: Working directory for commands (default: process.cwd())
SUDOCODE_ACTOR: Actor name for audit trail (default: process.env.USER)

Error Handling

CLI Not Found: Return helpful error directing to installation
Invalid Database: Suggest running init tool
Entity Not Found: Return 404-style error with clear message
Validation Errors: Parse CLI error output and return structured errors

Testing Strategy

Unit Tests: Mock CLI calls, test parameter mapping
Integration Tests: Real CLI calls with temp database
MCP Protocol Tests: Test tool registration and execution
Error Cases: Invalid inputs, missing entities, CLI errors

Future Enhancements

Batch Operations: Support bulk create/update/close
Search Tools: Full-text search across specs and issues
Sync Commands: Expose sync, export, import tools
Graph Queries: Advanced relationship traversal
Feedback Auto-Relocation: AI-assisted anchor relocation for stale feedback
Prompts: Add MCP prompts for common workflows (e.g., "start work on next task")

Reference Implementation

See references/beads/integrations/beads-mcp for similar Python-based MCP server architecture.

Sudocode MCP Server Specification

Overview

Sudocode MCP Server Specification

Overview

Architecture

Technology Stack

Design Principles

Resources

1. sudocode://quickstart

2. sudocode://workflow

Tools

Issue Management

1. ready

2. list_issues

3. show_issue

4. create_issue

5. update_issue

6. close_issue

7. blocked_issues

Spec Management

8. list_specs

9. show_spec

10. create_spec

Relationship Management

11. link

Feedback System

12. add_feedback

13. list_feedback

14. show_feedback

15. acknowledge_feedback

16. resolve_feedback

17. wontfix_feedback

18. stale_feedback

19. relocate_feedback

Analytics

20. stats

21. status

Initialization

22. init

Implementation Notes

CLI Client Architecture

Environment Variables

Error Handling

Testing Strategy

Future Enhancements

Reference Implementation

1. `sudocode://quickstart`

2. `sudocode://workflow`

1. `ready`

2. `list_issues`

3. `show_issue`

4. `create_issue`

5. `update_issue`

6. `close_issue`

7. `blocked_issues`

8. `list_specs`

9. `show_spec`

10. `create_spec`

11. `link`

12. `add_feedback`

13. `list_feedback`

14. `show_feedback`

15. `acknowledge_feedback`

16. `resolve_feedback`

17. `wontfix_feedback`

18. `stale_feedback`

19. `relocate_feedback`

20. `stats`

21. `status`

22. `init`