grokkit/todo/doing/mcp-feature.md

# MCP Server Feature

**Description**: Add an MCP (Model Context Protocol) server mode to grokkit, exposing its capabilities as tools and resources for Claude Code and other MCP-compatible clients.

## Problem It Solves

Grokkit's AI-powered code operations (linting, docs, test generation, analysis) are locked behind the CLI. MCP integration lets external AI clients invoke them programmatically, composing grokkit's strengths with broader workflows.

## Benefits

- **Composability**: Claude Code (or any MCP client) can call grokkit tools mid-conversation.
- **No core changes**: New `grokkit mcp` command wraps existing functionality via interfaces.
- **Stdio transport**: No HTTP server to manage — Claude Code pipes stdio directly.
- **Recipes as resources**: MCP clients can browse and invoke workflow recipes.
- **Leverages existing architecture**: `AIClient` and `GitRunner` interfaces already support dependency injection.

## Architecture Notes

Grokkit is well-suited for this:

- **Interface-based design**: `AIClient` and `GitRunner` are already abstractions — inject real implementations into MCP tool handlers.
- **Clean package separation**: Each internal package (grok, git, linter, recipe, prompts) maps naturally to an MCP tool.
- **Cobra command tree**: Adding `cmd/mcp.go` is trivial.
- **Streaming caveat**: MCP tools return complete results, so use `StreamSilent` (captures without printing) rather than `Stream`.
- **File-writing tools** (`edit`, `workon`): Need careful scoping so the MCP client understands what changed.

## High-Level Implementation

### Phase 1: Foundation

1. **Add MCP Go SDK** (e.g., `github.com/mark3labs/mcp-go`) to `go.mod`.
2. **Create `internal/mcp/server.go`** — MCP server that registers tools and resources.
3. **Create `cmd/mcp.go`** — `grokkit mcp` command that starts the stdio server.

### Phase 2: Tools

Wrap existing functionality as MCP tools. Priority order:

| Tool | Wraps | Notes |
|------|-------|-------|
| `lint_code` | `internal/linter` | Stateless. File path in, results out. |
| `generate_commit_msg` | `cmd/commit.go` logic | Reads git diff, calls Grok, returns message. |
| `analyze_code` | `cmd/analyze.go` + `internal/prompts` | File in, analysis out. |
| `generate_docs` | `cmd/docs.go` | File in, docs out (9 styles available). |
| `generate_tests` | `cmd/testgen.go` | File in, tests out. |
| `run_recipe` | `internal/recipe` | Recipe name + params in, results out. |

Each tool handler:
- Extracts core logic from the Cobra `RunE` function into a reusable function.
- Injects real `AIClient` and `GitRunner` implementations.
- Returns complete text results (no streaming to client).

### Phase 3: Resources

| Resource | Source | Description |
|----------|--------|-------------|
| `recipes://local` | `.grokkit/recipes/` | Project-local workflow recipes |
| `recipes://global` | `~/.local/share/grokkit/recipes/` | Global recipes |
| `prompts://language` | `.grokkit/prompts/` | Language-specific analysis prompts |

## Flags / Config

| Key | Description |
|-----|-------------|
| `mcp.enabled` | Enable MCP server mode |
| `mcp.tools` | List of tools to expose (default: all) |
| `mcp.resources` | List of resources to expose (default: all) |

## Implementation Notes

- **Entry point**: `grokkit mcp` starts stdio server, blocks until EOF.
- **No breaking changes**: Entirely additive — new command, new package.
- **Testing**: Mock `AIClient` and `GitRunner` interfaces; table-driven tests per tool.
- **Effort**: Medium (~300-500 LOC). SDK does the protocol heavy lifting.
- **Prereqs**: Choose and evaluate a Go MCP SDK.

## ROI

**High**. Turns grokkit from a standalone CLI into a composable service:

| Capability | Standalone | With MCP |
|------------|-----------|----------|
| Lint | `grokkit lint` | Claude calls it mid-review |
| Docs | `grokkit docs` | Claude generates docs in context |
| Tests | `grokkit testgen` | Claude generates + validates tests |
| Recipes | `grokkit recipe` | Claude orchestrates multi-step workflows |
| Analysis | `grokkit analyze` | Claude gets language-aware code analysis |
## Work Plan

1. **Evaluate and add MCP SDK**  
   - Research Go MCP SDKs (`github.com/mark3labs/mcp-go` or equivalent).  
   - Add to `go.mod`, run `go mod tidy`.  
   - Commit: `feat(mcp): add MCP SDK dependency`.

2. **Implement MCP server foundation** (`internal/mcp`)  
   - Create `internal/mcp/server.go`: Initialize stdio server, register tools/resources.  
   - Inject real `AIClient` and `GitRunner` impls.  
   - Use `StreamSilent` for non-streaming results.  
   - Commit: `feat(mcp): add MCP server foundation`.

3. **Add `cmd/mcp.go`**  
   - Cobra command `grokkit mcp` to start stdio server.  
   - Add config flags: `--tools`, `--resources` (comma-separated).  
   - Blocks until EOF.  
   - Test: Manual `grokkit mcp` + simple MCP client.  
   - Commit: `feat(mcp): add grokkit mcp CLI command`.

4. **Extract reusable functions from existing commands**  
   - `lint_code`: Extract from `cmd/lint.go` → `internal/linter.RunLint(path) string`.  
   - `generate_commit_msg`: Extract from `cmd/commit.go` → `internal/git.GenerateCommitMsg() string`.  
   - Commit per extraction: `refactor(lint): extract reusable lint function`.

5. **Implement Phase 2 tools** (priority order, 1 commit per 2 tools)  
   - Register each as MCP tool in `server.go`.  
   - `lint_code`, `analyze_code`.  
   - `generate_docs`, `generate_tests`.  
   - `generate_commit_msg`, `run_recipe`.  
   - Table-driven unit tests with mocked `AIClient`/`GitRunner`.  
   - Commit: `feat(mcp): add lint_code and analyze_code tools`.

6. **Implement Phase 3 resources**  
   - `recipes://local`, `recipes://global`, `prompts://language`.  
   - List directories and contents as MCP resources.  
   - Unit tests for path resolution and listing.  
   - Commit: `feat(mcp): add recipe and prompt resources`.

7. **Add config flags and validation**  
   - Support `mcp.enabled`, `mcp.tools`, `mcp.resources` in config.  
   - Validate tool/resource lists on startup.  
   - Integration test: Full `grokkit mcp` run with subset tools.  
   - Commit: `feat(mcp): add config flags and validation`.

8. **End-to-end testing and docs**  
   - Test with Claude Code or MCP client simulator.  
   - Add `README.md` section: "MCP Server Mode".  
   - Smoke test all tools/resources.  
   - Final commit: `feat(mcp): complete MCP server + docs/tests`.