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 |
|