io.github.DojoGenesis/mcp

Dojo Genesis MCP Server

The methodology layer for Claude Code. It encodes 99 first-party working methods across 10 behavioral plugins as active cognitive scaffolds: instead of giving Claude more data, it gives Claude structured methods for software development decisions.

We have not yet measured whether these scaffolds improve Claude's decisions, so this README makes no claim that they do.

Quick Install

Claude Code

Add to your project's .claude/settings.json:

{
  "mcpServers": {
    "dojo": {
      "command": "/path/to/dojo-mcp-server",
      "env": {
        "DOJO_SKILLS_PATH": "/path/to/CoworkPluginsByDojoGenesis",
        "DOJO_ADR_PATH": "./decisions"
      }
    }
  }
}

Or using Docker:

{
  "mcpServers": {
    "dojo": {
      "command": "docker",
      "args": ["run", "-i", "--rm", "ghcr.io/dojogenesis/mcp-server:latest"]
    }
  }
}

Claude Desktop

Add to ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):

{
  "mcpServers": {
    "dojo": {
      "command": "/path/to/dojo-mcp-server",
      "env": {
        "DOJO_SKILLS_PATH": "/path/to/CoworkPluginsByDojoGenesis",
        "DOJO_ADR_PATH": "./decisions"
      }
    }
  }
}

What's Included

Tools (28)

² Dispatch-class — spends LLM provider budget through the gateway. In HTTP mode these require a dispatch-enabled API key and are rate limited per key; dojo_scout's LLM path degrades to its offline scaffold for non-dispatch keys.

Skills (99 from CoworkPlugins, 43 bundled)

Skills are complete, battle-tested methodology workflows loaded from SKILL.md files at startup. When DOJO_SKILLS_PATH is set, all 99 first-party CoworkPlugins skills are available. Without it, 43 key skills across 8 plugins are embedded in the binary via go:embed.

Bundled plugins and skills:

Seed Patches (20)

Seeds are reusable thinking patterns drawn from across the Dojo ecosystem.

Dojo Genesis (Core)

AROMA & Serenity Valley

Resources

Documentation resources accessible via MCP resource URIs:

• dojo://resources/{name} -- 8 documentation resources (AROMA philosophy, EIT principles, etc.)
• dojo://seeds/{name} -- 20 seed patches
• dojo://skills/{plugin}/{name} -- All loaded skills

Configuration

The server works out of the box with zero configuration (bundled skills, default ADR path, stdio).

HTTP Mode (public endpoint)

Setting DOJO_HTTP_ADDR serves MCP streamable-HTTP instead of stdio:

• POST/GET /mcp — the MCP endpoint, Bearer-key required (Authorization: Bearer <key>). Keyless or wrong-key requests get 401.
• /mcp/k/<key> — same endpoint for clients that cannot send custom headers; the key is redacted in logs.
• GET /health — unauthenticated liveness (status + version only).

The server refuses to start in HTTP mode without a valid, non-empty DOJO_MCP_API_KEYS. Every tool call is logged as tool_call tool=… key=<label> dur_ms=… outcome=… — labels only, never key material, never payloads.

DOJO_HTTP_ADDR=:8091 \
DOJO_MCP_API_KEYS="win:$(openssl rand -hex 32)" \
./dojo-mcp-server

curl -s localhost:8091/health
curl -s -X POST localhost:8091/mcp \
  -H "Authorization: Bearer <key>" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-03-26","capabilities":{},"clientInfo":{"name":"curl","version":"0"}}}'

Client wiring (Claude Code): claude mcp add --transport http dojo-remote https://<host>/mcp --header "Authorization: Bearer <key>".

Deployment notes: ingress is expected to be a Cloudflare tunnel (no host ports); pin the container image by digest so auto-pull never surprise-deploys a new public surface. Image publishing: .github/workflows/docker-publish.yml → ghcr.io/dojogenesis/mcp (supersedes the old manually-pushed mcpbydojogenesis image).

Building from Source

git clone https://github.com/DojoGenesis/mcp.git
cd mcp

# Build
go build -o dojo-mcp-server ./cmd/server

# Run
./dojo-mcp-server

# Test
go test -race -v ./...

Requires Go 1.23 or later.

Docker

# Build the image
docker build -t dojo-mcp-server .

# Run via stdio (for MCP hosts)
docker run -i --rm dojo-mcp-server

# Run with skills path mounted
docker run -i --rm -v /path/to/CoworkPlugins:/skills -e DOJO_SKILLS_PATH=/skills dojo-mcp-server

Project Structure

mcp-server/
  cmd/server/main.go           Server entry point, env vars
  internal/
    dojo/
      handler.go                7 MCP tool handlers
      scaffolds.go              Scout and reflect methodology templates
    skills/
      loader.go                 Filesystem SKILL.md loader
      search.go                 Keyword + trigger search
      bundled.go                go:embed fallback (15 key skills)
      bundled/                  Embedded SKILL.md files
    decisions/
      writer.go                 ADR file writer
    wisdom/
      base.go                   Wisdom base, search, helpers
      seeds.go                  20 seed patches
      resources.go              8 documentation resources
  Dockerfile                    Multi-stage container build
  .github/workflows/ci.yml     CI pipeline
  .goreleaser.yml               Cross-platform release config

Philosophy

Dojo Genesis is built on three core principles:

1. Beginner's Mind -- Approach every interaction fresh, free from accumulated expertise.
2. Self-Definition -- Help users see their own thinking, not impose external frameworks.
3. Understanding is Love -- Deep, non-judgmental understanding is the highest service.

License

MIT License -- see LICENSE for details.

Copyright (c) 2026 Dojo Genesis

Contributing

Contributions are welcome. Please see github.com/DojoGenesis for organization-level guidelines.