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.
2026-05-29 18:12:45 +00:00
# Changelog — einherjar/mcp
All notable changes to this module are documented here.
Format follows [Keep a Changelog ](https://keepachangelog.com/en/1.1.0/ ).
This module adheres to [Semantic Versioning ](https://semver.org/spec/v2.0.0.html ).
---
feat(mcp): index struct fields and interface method sets (#1)
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.
Reviewed-on: https://code.nochebuena.dev/einherjar/mcp/pulls/1
Co-authored-by: Rene Nochebuena Guerrero <rene@nochebuena.dev>
Co-committed-by: Rene Nochebuena Guerrero <rene@nochebuena.dev>
2026-06-10 10:38:30 -06:00
## [0.2.0] — 2026-06-10
Minor release. The indexer now captures the * members * of composite types, closing a gap where `get_symbol` and `search_symbols` could name a struct or interface but not describe its shape — most painfully, struct tags (env-var keys, json names) were invisible.
### Added
- **Struct fields in the index.** Each struct-type symbol now carries a `fields` array — field name, type, raw struct tag (backticks stripped), doc comment, and an `embedded` marker. `get_symbol` returns it; previously the signature was truncated to the bare `type X struct` header, so field names, types, and tags (e.g. `env:"EINHERJAR_PG_HOST"` ) were dropped entirely.
- **Interface method sets in the index.** Each interface-type symbol now carries a `methods` array — method name, signature (without the leading `func` ), and doc comment, including embedded interfaces. Consumers can now see what a port like `db-postgres` `Provider` actually requires.
- **Search by field/tag/method.** `search_symbols` now also matches a query against struct field names, field types, and struct tags, and against interface method names/signatures — so an env-var key or a method name resolves to the type that declares it.
- **`internal/index` test suite** covering field, tag, embedded-field, interface-method, and search-by-tag capture (the package previously had no tests).
### Notes
- The index schema gains two optional (`omitempty` ) fields; `SchemaVersion` is unchanged because the change is additive and older consumers parse the new index unchanged.
- This is a pure indexer/schema change. The live server picks it up on its next image build, which re-runs `cmd/indexer` (see `Dockerfile` ). A deployment that has not been rebuilt will still serve the older, member-less index.
---
feat(mcp): systemd socket activation and healthz under /mcp (v0.1.1)
Patch release. Two changes to cmd/server, both motivated by running the
service behind a unix socket on a reverse-proxied host: the binary now
inherits a systemd-passed listener when present, and the healthz handler
moves under the same path prefix as the MCP endpoint so a single proxy
location forwards both. Bundled with two repository-hygiene changes.
cmd/server:
- chooseListener (new) — picks a listener at startup. When systemd has
passed a LISTEN_FDS fd via github.com/coreos/go-systemd/v22/activation,
the binary uses the inherited listener; otherwise it binds TCP at -addr
as before. The startup log records "mode":"socket-activated" or
"mode":"tcp" so operators can confirm which path is live. Same binary
works for local dev and for systemd-managed deployment with no flags
or env vars to toggle.
- Health probe path is now derived from -path. With the default -path /mcp
the probe is served at /mcp/healthz; the legacy /healthz route is no
longer registered. A reverse proxy can now route the whole MCP service
through a single "/mcp" location prefix instead of maintaining a second
forward for /healthz. Consumers of v0.1.0 that hit /healthz directly
must switch to /mcp/healthz.
Dependencies:
- github.com/coreos/go-systemd/v22 v22.7.0 — listener inheritance via
LISTEN_FDS. Loaded only by cmd/server.
Docs:
- README.md "Deployment" section rewritten to be hosting-agnostic. The
v0.1.0 draft prescribed a specific systemd-on-HestiaCP layout; the new
text points at the Dockerfile and at systemd socket activation as a
supported binary mode without dictating one operator's setup. Adds an
explicit note that any reverse proxy must disable response buffering on
the /mcp location — streamable MCP delivers tool results via Server-Sent
Events and default proxy buffering breaks the stream.
Repository hygiene:
- /deploy/ is now .gitignored. Local deployment artefacts (systemd units,
reverse-proxy templates, per-release scripts) are operator-specific by
design and live outside the public repository. The Dockerfile at the
module root remains the only portable, public-facing build artefact.
No tool surface, no validation rules, no index schema, and no behaviour of
the indexer changed. Operators upgrading from v0.1.0 must update their
health-probe URL to /mcp/healthz (or whichever path matches their -path
flag); MCP-protocol clients (Claude, Cursor, Zed, etc.) need no changes.
2026-05-29 14:09:06 -06:00
## [0.1.1] — 2026-05-29
Patch release. Two changes to `cmd/server` make the binary cleaner to run behind a unix socket on a reverse-proxied host, plus two repository-hygiene changes that follow from the same deployment exercise.
### Added
- **Systemd socket activation** in `cmd/server` . The binary inherits the listener from `LISTEN_FDS` via `github.com/coreos/go-systemd/v22/activation` when present, falling back transparently to TCP `-addr` binding otherwise. Startup log records `"mode":"socket-activated"` or `"mode":"tcp"` . Same binary, no flag or env var to toggle.
### Changed
- **Health probe path** moved from `/healthz` to `<path>/healthz` (default `/mcp/healthz` ). Lets a reverse proxy expose the entire MCP service through one location prefix. v0.1.0 consumers hitting the old `/healthz` route receive 404; update to `/mcp/healthz` (or whatever path matches your `-path` flag).
- **`README.md` deployment section** rewritten to be hosting-agnostic. Points at the `Dockerfile` and systemd socket activation as supported binary modes without prescribing one operator's setup. Adds the SSE-buffering caveat once: any reverse proxy must disable response buffering on the `/mcp` location, otherwise Server-Sent Events get batched and streamable MCP sessions break.
- **`/deploy/` ** is now `.gitignored` . Local deployment artefacts (systemd units, reverse-proxy templates, per-release scripts) are operator-specific by design and live outside the public repository. The `Dockerfile` at the module root remains the only portable, public-facing build artefact.
### Dependencies
- **Added:** `github.com/coreos/go-systemd/v22 v22.7.0` — used by `cmd/server` to detect and use a systemd-passed listener.
### Upgrade notes
| If you… | Action |
|---|---|
| Consume the MCP service from an MCP client (Claude, Cursor, Zed, etc.) | None — `/mcp` is unchanged |
| Monitor the service via the healthz probe | Update the probe URL from `/healthz` to `/mcp/healthz` |
| Run the binary directly (no reverse proxy) | None — `-addr` TCP binding still works the same way |
| Run the binary under systemd with a socket unit | The same binary now picks up the inherited listener automatically |
---
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.
2026-05-29 18:12:45 +00:00
## [0.1.0] — 2026-05-29
Initial release. The `mcp` module hosts the **Einherjar Model Context Protocol server ** — a remote, streamable-HTTP service that teaches AI assistants about every other module of the framework.
### Added
#### Server (`cmd/server`)
- Streamable-HTTP MCP server built on `github.com/modelcontextprotocol/go-sdk` v1.0.0
- Listen address and HTTP path configurable via `EINHERJAR_MCP_ADDR` (default `:8080` ) and `EINHERJAR_MCP_PATH` (default `/mcp` )
- `/healthz` liveness endpoint
- Embedded framework index loaded once at startup; in-memory for the lifetime of the process
#### Indexer (`cmd/indexer`)
- Walks an Einherjar repository checkout and produces `data/index.json`
- For each sibling module captures: import path, Go version, README (full + extracted tagline), CHANGELOG, root `doc.go` package comment, sub-package doc comments, every exported symbol (type/interface/func/method/const/var) with signature + godoc, ADRs, README code-fence examples, dependency edges from `go.mod` , and the contents of `compliance_test.go` (interface assertions + structural test names)
- Appends a synthetic `wire` module documenting canonical Einherjar application wiring conventions
#### Tools (10)
- `list_modules` — enumerate every Einherjar module with purpose and sub-packages
- `get_module` — package doc, dependencies, sub-packages, key symbols, ADRs, compliance counts; optional embedded README
- `search_symbols` — full-text search across name, doc, sub-package, module
- `get_symbol` — full signature, doc, and source location for one symbol
- `list_adrs` — list architectural decision records, optionally filtered by module
- `get_adr` — fetch one ADR's markdown body
- `get_example` — canonical usage snippets extracted from module READMEs and the `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
#### Validation rules (8)
- `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` , `wire.route-specific-after-param`
#### Synthetic `wire` module
- Authored in `internal/index/builtins/README.md` ; participates in `list_modules` , `get_module` , and `get_example` exactly like a real module
- Sections: project layout, `Run()` shape, feature hook shape, route ordering, authorization, middleware helpers, adapters at the wire boundary, migrations and seeds
- All examples use einherjar import paths
#### Packaging
- Multi-stage `Dockerfile` that builds from the einherjar repository root (`docker build -f mcp/Dockerfile .` ) so the indexer can walk every sibling module at image-build time
- Distroless runtime image; static binary; non-root user
