feat(mcp): initial implementation — MCP server, framework indexer, 10 tools, 8 validation rules (v0.1.0)
Introduces code.nochebuena.dev/einherjar/mcp — the Einherjar Model Context Protocol
server. A remote, streamable-HTTP service that teaches AI assistants about every
other module of the framework: which package exposes which type, what each module
guarantees through its compliance tests, the canonical wiring shape for a service,
and whether a Go snippet follows the conventions. Indexes the framework on disk at
build time and ships a self-contained binary via go:embed; imports nothing from
other einherjar/* modules at compile time.
server (cmd/server):
- Streamable-HTTP MCP server built on github.com/modelcontextprotocol/go-sdk v1.0.0
- mcp.NewServer + mcp.NewStreamableHTTPHandler, served via net/http on EINHERJAR_MCP_ADDR
(default :8080) and EINHERJAR_MCP_PATH (default /mcp)
- /healthz liveness endpoint; structured JSON logging via log/slog
- Loads the embedded data/index.json once at startup; in-memory for the process lifetime
indexer (cmd/indexer):
- Walks an Einherjar repository checkout (default ../), parses every sibling
module's go.mod, README.md, CHANGELOG.md, docs/adr/ADR-*.md, doc.go package
comments, every exported type/interface/func/method/const/var (via go/doc on
go/parser ASTs), and compliance_test.go
- Captures module dependency edges by regex over each go.mod's require lines
(einherjar/* paths only; self-reference filtered)
- Appends a synthetic "wire" module documenting canonical application wiring
conventions, authored at internal/index/builtins/README.md and embedded via
go:embed; participates in list_modules / get_module / get_example like a real module
internal/index:
- Schema einherjar.mcp/index/v1; types: Index, Module, SubPackage, Symbol, ADR,
Example, Compliance, InterfaceAssert, ComplianceTest
- Build(repoRoot) → *Index walks the repo; BuildBuiltins() returns the synthetic
wire module from the embedded markdown
- Load([]byte) → *Index validates the schema version on read
- FindModule, SearchSymbols helpers used by tools
internal/tools (10 tools):
- list_modules — enumerate every module with purpose + sub-packages
- get_module — package doc, dependencies, sub-packages, key symbols, ADRs,
compliance counts; optional embedded README
- search_symbols — full-text across name, doc, sub-package, module; filterable by
module and kind
- get_symbol — full signature, doc comment, source file:line for one symbol
- list_adrs — list ADRs across the framework or within one module
- get_adr — fetch one ADR's markdown body
- get_example — canonical usage snippets extracted from module READMEs and from
the synthetic wire conventions
- get_compliance — interface assertions (var _ Iface = impl) and structural test
names from a module's compliance_test.go
- get_changelog — full CHANGELOG.md markdown for one module
- validate_snippet — pattern-match a Go snippet against framework conventions
internal/rules (8 rules, registered via init() against a single registered slice):
- launcher.missing-run — launcher constructed but Run() never called
- launcher.no-components — launcher.New() called without any .Append(...)
- launcher.run-error-discarded — lc.Run() invoked as an ExprStmt (return ignored)
- logz.direct-env-read — os.Getenv("EINHERJAR_LOG_*") bypassing logz config
- web.server-not-appended — web/server constructed but not added to the launcher
- wire.hook-bad-signature — with<Feature>(...) first param is not launcher.Launcher
- wire.hook-outside-beforestart — repo/service/handler construction or route
registration at the top level of a hook (outside lc.BeforeStart)
- wire.route-specific-after-param — /users/{id} registered before a sibling
/users/me of the same length and method (chi would shadow the literal route)
Synthetic wire module (internal/index/builtins/README.md):
- Project layout (cmd/<app>/main.go + internal/wire/*.go + per-feature domain dirs)
- Canonical Run() shape: config → logger → infra (db, cache, pool, mc, srv) → cross-
cutting (validator, permission provider) → launcher.New → lc.Append(infra...) →
withMigrations / withSuperAdminSeed / withHealth / withFeature hooks → return lc.Run()
- Canonical with<Feature> hook shape: signature (launcher.Launcher first, server.Server
second, deps last), single lc.BeforeStart closure containing all construction +
route registration
- chi route ordering, srv.With(authz(...)) authorization, middleware helpers
(authz / skipPublicPaths / skipMethodPath), tokenSignerAdapter pattern showing
that the framework exposes Signer.Sign as a primitive and the application owns
the access/refresh response shape
Packaging:
- Multi-stage Dockerfile that builds from the einherjar repository root
(docker build -f mcp/Dockerfile .) so cmd/indexer can walk every sibling module
at image-build time; runtime layer is gcr.io/distroless/static-debian12:nonroot
- 86-byte placeholder data/index.json committed once with `git add -f`; subsequent
indexer runs overwrite it locally but the file is .gitignored
- .gitea/CODEOWNERS and pull_request_template.md mirror the sibling layout
Design notes:
- mcp depends on nothing in einherjar/* — it reads the framework via the filesystem
at index time. This keeps mcp outside the framework dependency graph and lets it
index any version of einherjar without versioning itself in lock-step.
- All structured-output tool responses initialise empty slices ([]Type{}) rather
than relying on Go's nil-marshals-to-null default, so the SDK's JSON-schema
output validator never rejects a tools/call result.
This commit is contained in:
164
internal/index/index.go
Normal file
164
internal/index/index.go
Normal file
@@ -0,0 +1,164 @@
|
||||
// Package index defines the on-disk schema of the Einherjar framework index
|
||||
// and provides a loader for the embedded JSON blob.
|
||||
//
|
||||
// The index is built once at deploy time by cmd/indexer and consumed by every
|
||||
// MCP tool. Keeping it small, denormalised, and JSON-shaped means tools can
|
||||
// be implemented as straightforward in-memory filters.
|
||||
package index
|
||||
|
||||
import (
|
||||
"encoding/json"
|
||||
"fmt"
|
||||
"strings"
|
||||
"time"
|
||||
)
|
||||
|
||||
// SchemaVersion identifies the on-disk index format. Bump when fields change
|
||||
// in a way that breaks older consumers.
|
||||
const SchemaVersion = "einherjar.mcp/index/v1"
|
||||
|
||||
// Index is the root of the embedded framework knowledge.
|
||||
type Index struct {
|
||||
Schema string `json:"schema"`
|
||||
Framework string `json:"framework"`
|
||||
BuiltAt time.Time `json:"builtAt"`
|
||||
Modules []Module `json:"modules"`
|
||||
}
|
||||
|
||||
// Module describes one Einherjar module (e.g. core, web, auth-jwt).
|
||||
type Module struct {
|
||||
Name string `json:"name"`
|
||||
ImportPath string `json:"importPath"`
|
||||
Purpose string `json:"purpose"`
|
||||
Doc string `json:"doc,omitempty"`
|
||||
GoVersion string `json:"goVersion"`
|
||||
DependsOn []string `json:"dependsOn"`
|
||||
SubPackages []SubPackage `json:"subPackages"`
|
||||
Symbols []Symbol `json:"symbols"`
|
||||
ADRs []ADR `json:"adrs"`
|
||||
Examples []Example `json:"examples"`
|
||||
Compliance Compliance `json:"compliance"`
|
||||
Readme string `json:"readme,omitempty"`
|
||||
Changelog string `json:"changelog,omitempty"`
|
||||
}
|
||||
|
||||
// Compliance captures a module's compliance_test.go contents: compile-time
|
||||
// interface assertions and the names of structural tests. It exists so an AI
|
||||
// assistant can know about machine-checked conventions before it writes code
|
||||
// that would violate them.
|
||||
type Compliance struct {
|
||||
InterfaceAsserts []InterfaceAssert `json:"interfaceAsserts"`
|
||||
Tests []ComplianceTest `json:"tests"`
|
||||
}
|
||||
|
||||
// InterfaceAssert mirrors one `var _ Iface = impl` line in compliance_test.go.
|
||||
type InterfaceAssert struct {
|
||||
Module string `json:"module"`
|
||||
Interface string `json:"interface"`
|
||||
Impl string `json:"impl"`
|
||||
File string `json:"file"`
|
||||
Line int `json:"line"`
|
||||
}
|
||||
|
||||
// ComplianceTest mirrors one Test* function in compliance_test.go.
|
||||
type ComplianceTest struct {
|
||||
Module string `json:"module"`
|
||||
Name string `json:"name"`
|
||||
Doc string `json:"doc"`
|
||||
File string `json:"file"`
|
||||
Line int `json:"line"`
|
||||
}
|
||||
|
||||
// SubPackage is one importable sub-package of a module.
|
||||
type SubPackage struct {
|
||||
Name string `json:"name"`
|
||||
ImportPath string `json:"importPath"`
|
||||
Doc string `json:"doc"`
|
||||
}
|
||||
|
||||
// Symbol is one exported declaration (type, func, interface, const, var).
|
||||
type Symbol struct {
|
||||
Module string `json:"module"`
|
||||
SubPackage string `json:"subPackage"`
|
||||
Kind string `json:"kind"`
|
||||
Name string `json:"name"`
|
||||
Signature string `json:"signature"`
|
||||
Doc string `json:"doc"`
|
||||
File string `json:"file"`
|
||||
Line int `json:"line"`
|
||||
}
|
||||
|
||||
// ADR is one architectural decision record.
|
||||
type ADR struct {
|
||||
Module string `json:"module"`
|
||||
ID string `json:"id"`
|
||||
Title string `json:"title"`
|
||||
Body string `json:"body"`
|
||||
}
|
||||
|
||||
// Example is a fenced code block lifted from a module README.
|
||||
type Example struct {
|
||||
Module string `json:"module"`
|
||||
SubPackage string `json:"subPackage"`
|
||||
Title string `json:"title"`
|
||||
Code string `json:"code"`
|
||||
Language string `json:"language"`
|
||||
}
|
||||
|
||||
// Load parses the embedded JSON blob into an Index. It validates the schema
|
||||
// version and returns an empty (but non-nil) Index when the blob is the
|
||||
// placeholder shipped before the indexer has been run.
|
||||
func Load(raw []byte) (*Index, error) {
|
||||
if len(raw) == 0 {
|
||||
return &Index{Schema: SchemaVersion, Framework: "einherjar"}, nil
|
||||
}
|
||||
idx := &Index{}
|
||||
if err := json.Unmarshal(raw, idx); err != nil {
|
||||
return nil, fmt.Errorf("index: parse: %w", err)
|
||||
}
|
||||
if idx.Schema != "" && idx.Schema != SchemaVersion {
|
||||
return nil, fmt.Errorf("index: schema mismatch: got %q want %q", idx.Schema, SchemaVersion)
|
||||
}
|
||||
return idx, nil
|
||||
}
|
||||
|
||||
// FindModule returns the module with the given name, or nil if absent.
|
||||
func (i *Index) FindModule(name string) *Module {
|
||||
for k := range i.Modules {
|
||||
if i.Modules[k].Name == name {
|
||||
return &i.Modules[k]
|
||||
}
|
||||
}
|
||||
return nil
|
||||
}
|
||||
|
||||
// SearchSymbols returns up to limit symbols whose name or doc contains q
|
||||
// (case-insensitive). Module name and sub-package are also searched.
|
||||
func (i *Index) SearchSymbols(q string, limit int) []Symbol {
|
||||
if limit <= 0 {
|
||||
limit = 25
|
||||
}
|
||||
needle := strings.ToLower(q)
|
||||
out := make([]Symbol, 0, limit)
|
||||
for _, m := range i.Modules {
|
||||
for _, s := range m.Symbols {
|
||||
if matches(s, needle) {
|
||||
out = append(out, s)
|
||||
if len(out) >= limit {
|
||||
return out
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
return out
|
||||
}
|
||||
|
||||
func matches(s Symbol, needle string) bool {
|
||||
if needle == "" {
|
||||
return true
|
||||
}
|
||||
return strings.Contains(strings.ToLower(s.Name), needle) ||
|
||||
strings.Contains(strings.ToLower(s.Doc), needle) ||
|
||||
strings.Contains(strings.ToLower(s.SubPackage), needle) ||
|
||||
strings.Contains(strings.ToLower(s.Module), needle)
|
||||
}
|
||||
Reference in New Issue
Block a user