grokkit/todo/completed/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.