Rene Nochebuena
1586ed4d52
Minor release. The indexer named composite types but could not describe their shape: every declaration was truncated at the first brace, so a struct symbol carried only its `type X struct` header and an interface symbol only its `type X interface` header. Field names, field types, and — most painfully — struct tags such as `env:"EINHERJAR_PG_HOST"` were dropped, as were the method sets of every port interface. An assistant could be told that `db-postgres` has a `Config` and a `Provider`, but not what env vars configure the one or what methods the other requires. This change captures both. internal/index (schema): - Symbol gains two optional fields. `fields` ([]Field) carries a struct's field set — name, type, raw struct tag (surrounding backticks stripped), doc comment, and an `embedded` marker. `methods` ([]Method) carries an interface's method set — name, signature without the leading `func`, and doc comment, including embedded interfaces. Both are omitempty and absent for every other kind. - SchemaVersion is deliberately unchanged. The two additions are additive and omitempty, so an older consumer parses the new index unchanged; per the existing rule the constant only bumps on a breaking format change. internal/index (builder): - collectSymbols now inspects each type's TypeSpec and, for a *ast.StructType or *ast.InterfaceType, fills the new Symbol members. A grouped field declaration (`x, y int`) yields one Field per name; an embedded field or interface yields an entry with an empty name. - New helpers: typeSpecType (underlying type expr of a lone type spec), extractFields, extractIfaceMethods, fieldDoc (doc comment or trailing line comment), and nodeString — a non-truncating printer used for field types, tags, and method signatures, distinct from formatNode which keeps truncating to produce the one-line header. internal/index (search): - matches() now also tests the query against struct field names, field types, and struct tags, and against interface method names and signatures. A query like an env-var key or a method name now resolves to the type that declares it. internal/tools: - get_symbol and search_symbols descriptions updated to advertise the new struct-field and interface-method coverage. No input/output schema change beyond the additive Symbol fields, which get_symbol already returns whole. internal/index (tests): - New builder_test.go — the package previously had no tests. Builds a temporary module fixture and asserts capture of struct fields (with tags and docs), embedded fields, interface methods (with signatures and docs), embedded interfaces, and discovery of a struct by one of its struct tags (the failure mode that motivated the change). Docs: - CHANGELOG.md gains an [Unreleased] entry; README.md tool table updated to state that get_symbol returns struct fields and interface methods and that search_symbols matches fields, tags, and methods. No new dependencies. The committed data/index.json placeholder is untouched — the index is regenerated at image build (Dockerfile runs cmd/indexer), so a deployment must be rebuilt to serve the richer index; a server still running the prior image keeps serving the older, member-less one.
203 lines
8.2 KiB
Markdown
203 lines
8.2 KiB
Markdown
# einherjar/mcp
|
|
|
|
[](https://code.nochebuena.dev/einherjar/mcp)
|
|
[](LICENSE)
|
|
[](https://go.dev)
|
|
|
|
> Every warrior who knew the sagas had a skald nearby. This is yours.
|
|
|
|
`code.nochebuena.dev/einherjar/mcp` is the Einherjar **Model Context Protocol** server.
|
|
It is a remote, streamable-HTTP service that teaches AI assistants about every other
|
|
module of the framework: which package exposes which type, what each module promises
|
|
via its compliance tests, the canonical wiring shape for a service, and whether a
|
|
snippet of Go follows the conventions. Anyone who works in an Einherjar codebase can
|
|
point their AI tools at one URL and get answers grounded in the actual source.
|
|
|
|
---
|
|
|
|
## What Is Einherjar?
|
|
|
|
In Norse mythology, the Einherjar are the chosen warriors of Valhalla — selected not
|
|
for glory, but to be ready for what comes after. They train. They prepare. They build
|
|
the capability that others will rely on.
|
|
|
|
This framework is named for that purpose. Every module is a piece of that preparation:
|
|
built carefully, documented for those who were never in the room, and designed to hold
|
|
under pressure.
|
|
|
|
---
|
|
|
|
## Commands
|
|
|
|
| Command | Purpose |
|
|
|---|---|
|
|
| `cmd/server` | Streamable-HTTP MCP server. Embeds the framework index at build time and serves it over a single HTTP endpoint. |
|
|
| `cmd/indexer` | Walks an Einherjar repository checkout and writes the framework index to `data/index.json`. |
|
|
|
|
---
|
|
|
|
## Tools
|
|
|
|
The server exposes **ten** tools to MCP-aware clients (Claude desktop, Claude Code,
|
|
Cursor, Zed, and anything else that speaks MCP):
|
|
|
|
| Tool | Purpose |
|
|
|---|---|
|
|
| `list_modules` | Enumerate every Einherjar module with its purpose and sub-packages |
|
|
| `get_module` | Package doc, dependencies, sub-packages, key types, compliance counts; optional README |
|
|
| `search_symbols` | Find a type, function, or interface by name, doc text, sub-package, module — or by a struct field/tag or an interface method |
|
|
| `get_symbol` | Full signature, doc comment, and source location for one symbol — plus struct fields (with tags) and interface method sets |
|
|
| `list_adrs` | List architectural decision records, optionally restricted to one module |
|
|
| `get_adr` | Fetch a single ADR's markdown body |
|
|
| `get_example` | Canonical usage snippet — pulled from module READMEs and from the synthetic `wire` conventions |
|
|
| `get_compliance` | Interface assertions 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; returns findings with severity, hint, and line |
|
|
|
|
`validate_snippet` ships **eight** wiring-convention rules at v0.1.0:
|
|
`launcher.missing-run`, `launcher.no-components`, `launcher.run-error-discarded`,
|
|
`logz.direct-env-read`, `web.server-not-appended`, `wire.hook-bad-signature`,
|
|
`wire.hook-outside-beforestart`, and `wire.route-specific-after-param`.
|
|
|
|
---
|
|
|
|
## Build Flow
|
|
|
|
```
|
|
build time runtime
|
|
┌──────────────────────────────┐ ┌──────────────────────────┐
|
|
│ cmd/indexer ../ │ │ cmd/server │
|
|
│ walks every Einherjar │ │ streamable-HTTP MCP │
|
|
│ module, parses Go pkgs, │ ──▶ │ tools served from the │
|
|
│ reads READMEs + ADRs │ │ embedded index.json │
|
|
│ ⇒ data/index.json (embed) │ │ │
|
|
└──────────────────────────────┘ └──────────────────────────┘
|
|
```
|
|
|
|
The indexer is a separate command. It produces `data/index.json` which the server
|
|
embeds via `//go:embed`, so the deployed binary is self-contained and reads nothing
|
|
from disk at runtime.
|
|
|
|
---
|
|
|
|
## Usage
|
|
|
|
### Local run
|
|
|
|
```bash
|
|
# 1. Build the framework index from the sibling Einherjar modules
|
|
go run ./cmd/indexer ..
|
|
|
|
# 2. Build and run the server
|
|
go build -o bin/einherjar-mcp ./cmd/server
|
|
./bin/einherjar-mcp -addr :8080 -path /mcp
|
|
```
|
|
|
|
### Container
|
|
|
|
```bash
|
|
# Build the image from the einherjar repo root so the indexer can walk every
|
|
# sibling module at image-build time.
|
|
docker build -f mcp/Dockerfile -t einherjar-mcp:0.1.0 .
|
|
|
|
docker run --rm -p 8080:8080 einherjar-mcp:0.1.0
|
|
```
|
|
|
|
### Environment variables
|
|
|
|
| Variable | Default | Effect |
|
|
|---|---|---|
|
|
| `EINHERJAR_MCP_ADDR` | `:8080` | Listen address for the MCP server |
|
|
| `EINHERJAR_MCP_PATH` | `/mcp` | HTTP path served by the streamable-HTTP endpoint |
|
|
|
|
---
|
|
|
|
## Wiring Conventions (the synthetic `wire` module)
|
|
|
|
The MCP server ships a 15th, **synthetic** module called `wire`. It is not an
|
|
Einherjar module — it documents the canonical *application* shape that uses Einherjar
|
|
modules. The content lives at `internal/index/builtins/README.md` and is embedded at
|
|
build time. AI assistants discover it via `list_modules` and read it via `get_module`
|
|
and `get_example` the same way they read any real module.
|
|
|
|
The conventions captured: project layout (`cmd/<app>/main.go`, `internal/wire/*.go`,
|
|
domain layout per feature), the fixed shape of `Run()`, the fixed shape of a
|
|
`with<Feature>` hook (one `lc.BeforeStart` containing all construction and route
|
|
registration), route-ordering rules for chi, the `authz` middleware helper, when to
|
|
use `skipPublicPaths` vs `skipMethodPath`, and adapter patterns at the wire boundary.
|
|
|
|
---
|
|
|
|
## Dependency Rules
|
|
|
|
```
|
|
contracts (zero dependencies)
|
|
↑
|
|
core, web, auth, … (every framework module)
|
|
↑
|
|
mcp (reads framework source at index-time only)
|
|
```
|
|
|
|
`mcp` imports **nothing** from other Einherjar modules at compile time. The indexer
|
|
parses the framework source on disk and writes a JSON blob; the server embeds that
|
|
blob. This keeps `mcp` outside the framework dependency graph: it can index any
|
|
version of einherjar without versioning itself in lock-step.
|
|
|
|
---
|
|
|
|
## Verification
|
|
|
|
```bash
|
|
cd mcp/
|
|
go build ./... # must compile clean
|
|
go vet ./... # no warnings
|
|
go test ./... # all tests pass
|
|
gofmt -l . # no output
|
|
```
|
|
|
|
All four commands must produce clean output before a PR will be reviewed.
|
|
|
|
---
|
|
|
|
## Deployment
|
|
|
|
The server is a single self-contained static binary. There is no canonical
|
|
hosting shape — pick whichever matches the rest of your infrastructure. Two
|
|
patterns cover most cases:
|
|
|
|
- **Container.** The [`Dockerfile`](Dockerfile) at the module root produces a
|
|
distroless runtime image. Build from the einherjar repository root so the
|
|
indexer can reach every sibling module at image-build time:
|
|
|
|
```bash
|
|
docker build -f mcp/Dockerfile -t einherjar-mcp:0.1.0 .
|
|
docker run --rm -p 8080:8080 einherjar-mcp:0.1.0
|
|
```
|
|
|
|
- **Systemd / socket-activated binary.** The server detects an inherited
|
|
listener via `github.com/coreos/go-systemd/v22/activation` and uses it when
|
|
present, falling back to `-addr` TCP binding otherwise. Same binary works in
|
|
both modes — no flag, no env var. Drop the binary into `/opt/<somewhere>/`
|
|
and write a `.socket` + `.service` pair that matches your conventions.
|
|
|
|
Whatever shape you pick, the public-facing reverse proxy must keep response
|
|
buffering **off** on the `/mcp` location. Streamable MCP delivers tool results
|
|
via Server-Sent Events; default nginx, Envoy, or Caddy buffering batches the
|
|
stream and breaks Claude's session before the first event arrives. For nginx
|
|
that means `proxy_buffering off; proxy_cache off; proxy_request_buffering off;
|
|
chunked_transfer_encoding on;` plus an extended `proxy_read_timeout` for
|
|
long-lived sessions.
|
|
|
|
---
|
|
|
|
## Architecture Decisions
|
|
|
|
No ADRs at `v0.1.0`. The structural decisions in this release (synthetic `wire`
|
|
module, `go:embed` of the index, build-time-not-runtime knowledge model, primitives
|
|
not response shapes) are captured in the framework-wide memory and in this README.
|
|
|
|
---
|
|
|
|
> *A blade is sharper when the warrior knows its name.*
|
|
> *This is what tells them.*
|