Greg Gauthier
d701ee3793
Introduces a detailed plan in todo/queued/mcp-feature.md for integrating an MCP server into grokkit, enabling programmatic access to AI-powered code tools and resources via stdio for clients like Claude Code. Includes architecture notes, implementation phases, tools, resources, and ROI analysis.
88 lines
4.0 KiB
Markdown
88 lines
4.0 KiB
Markdown
# 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 |
|