Sudocode MCP

Model Context Protocol (MCP) server for sudocode - A git-native spec and issue management system designed for AI-assisted development.

Features

- MCP Tools for complete issue and spec management
- Git-native workflow - All data stored in git
- Anchored feedback - Link issues to specific lines in specs with smart relocation
- Relationship tracking - Model dependencies and blockers
- CLI-first design - Wraps existing sudocode CLI commands

Installation

``bash
npm install -g sudocode
`

Or to install just the MCP server and CLI:
`bash
npm install -g @sudocode-ai/cli @sudocode-ai/mcp
`

Configuration

IMPORTANT: Before using this MCP server, sudocode MUST be initialized in your project directory (sudocode init)

$3


1. Navigate to your project root directory
2. Run: \sudocode init\
3. This creates the \.sudocode/\ directory with necessary database files
4. Verify setup: Check that \.sudocode/cache.db\ exists

Without initialization, all MCP tools will fail with errors.

If you see errors about missing database or .sudocode directory, run \sudocode init\ first.

$3

Option 1: Install via Plugin (Recommended)

`bash
/plugin marketplace add sudocode-ai/sudocode
/plugin install sudocode
`

The plugin handles MCP server setup automatically. See .claude-plugin/README.md for details.

Option 2: Manual MCP Configuration

If you've installed via npm, add to your Claude Code configuration:

`json
{
"mcpServers": {
"sudocode": {
"command": "sudocode-mcp"
}
}
}
`

$3

`json
{
"mcpServers": {
"sudocode": {
"command": "sudocode-mcp",
"env": {
"SUDOCODE_WORKING_DIR": "/path/to/your/project",
"SUDOCODE_PATH": "sudocode",
}
}
}
}
`

Environment Variables

- SUDOCODE_PATH - Path to sudocode CLI executable (default: sudocode)
- SUDOCODE_WORKING_DIR - Working directory for sudocode (default: current directory)
- SUDOCODE_DB - Custom database path (default: .sudocode/cache.db)
- SUDOCODE_ACTOR - Actor name for operations (default: system username)

Available Tools

$3

- ready - Find issues and specs with no blockers
- list_issues - List issues with filters (status, type, priority, assignee)
- show_issue - Show detailed issue information
- upsert_issue - Create/update issue

$3

- list_specs - List specs with filters (status, type, priority)
- show_spec - Show detailed spec information with feedback
- upsert_spec - Create/update a specification

$3

- link - Create relationships between entities (blocks, implements, references, depends-on, parent-child, discovered-from, related)

$3

- add_reference - Add inline cross-reference to spec or issue using Obsidian-style [[ID]] syntax. Insert references at specific locations (line or text-based) with optional display text and relationship types.

$3

- upsert_feedback - Create/update anchored feedback to specs

Prerequisites

You must have the sudocode CLI (aliased sudocode or sdc) installed and available in your PATH.

Install sudocode:

`bash
npm install -g sudocode
`

Usage Example

Once configured in Claude Code, you can ask Claude to:

1. Find ready tasks: "Show me issues that are ready to work on"
2. Claim work: "Set issue ISSUE-123 to in_progress status"
3. Review specs: "Show me the spec for issue ISSUE-123"
4. Add cross-references: "Add a reference to ISSUE-042 in the requirements section of SPEC-010"
5. Provide feedback: "Add feedback to spec SPEC-005 about the authentication section"
6. Complete work: "Close issue ISSUE-123"

Development

$3

`bash
git clone https://github.com/sudocode-ai/sudocode.git
cd sudocode/mcp
npm install
npm run build # Uses esbuild for bundled & minified output
`

The build process:
- Bundles and minifies src/index.ts → dist/index.js (18 KB)
- Generates TypeScript declarations
- Sets executable permissions automatically

$3

`bash
npm test # Run all tests in watch mode
npm test -- --run # Run once
npm run test:unit # Unit tests only
`

$3

`bash
npm run build # Production build (esbuild - bundled & minified)
npm run build:dev # Development build (tsc - preserves structure)
npm run dev # Watch mode for development
npm run clean # Remove build output
`

$3

`
mcp/
├── src/
│ ├── client.ts # CLI wrapper
│ ├── server.ts # MCP server
│ ├── types.ts # Type definitions
│ └── tools/ # Tool implementations
│ ├── issues.ts
│ ├── specs.ts
│ ├── feedback.ts
│ ├── relationships.ts
│ ├── references.ts
│ ├── analytics.ts
│ └── init.ts
├── tests/
│ └── unit/ # Unit tests
└── dist/ # Built output
`

Troubleshooting

$3

If you get "CLI not found" errors:

1. Ensure sudocode is installed and in your PATH
2. Try setting SUDOCODE_PATH to the full path of the sudocode executable
3. Restart Claude Code after configuration changes

$3

If you get database errors:

1. Run sudocode init in your project directory first
2. Ensure the working directory is set correctly
3. Check that .sudocode/cache.db exists

$3

Ensure you have read/write access to:

- The project directory
- The .sudocode` directory
- The database file

Contributing

Contributions are welcome! Please see the main sudocode repository for contribution guidelines.

License

MIT License - see LICENSE file for details.

Links

- sudocode Main Repository
- Issue Tracker
- Model Context Protocol