grokkit/todo/queued/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