einherjar/mcp
2
0
Fork 0
Code Issues Pull Requests Packages Releases Activity
Files
a0b803cb404a9652bd281b9aa751daf59b7a8e2f
mcp/CHANGELOG.md
T
Rene Nochebuena a0b803cb40 feat(mcp): scaffold tool, config/env conventions, and scaffold-hygiene rules (#2) 
Major release to v1.0.0, aligned with the v1.0.0 framework. The MCP documented
the wiring conventions but not the config half of a project, and its example
main.go omitted the godotenv autoload — so an assistant starting a service from
zero still hand-rolled main.go and the launcher, and got config wrong. This adds
a first-class scaffold, completes the config/.env.example conventions, and adds
rules that catch the "mess in main" pattern.

internal/tools:
- New get_scaffold: returns the canonical minimum application scaffold as
  ready-to-write files (main.go with godotenv autoload + wire.Run(), wire.go,
  a composed config.go, a health hook, .env.example), with import paths filled
  from a `module` argument. Registered in tools.go.

internal/rules:
- Three new validate_snippet rules, appended in scaffold_rules.go: main.dirty
  (launcher/components built in main instead of internal/wire),
  main.no-godotenv-autoload (a wire-convention main that never loads .env), and
  config.raw-getenv (an EINHERJAR_* var read via os.Getenv instead of composing
  the component Config; EINHERJAR_LOG_* stays with logz.direct-env-read).
- scaffold_rules_test.go — internal/rules had no tests; asserts each new rule
  fires and that a clean main is not flagged.

internal/index (builtins):
- The synthetic wire module gains a Config section (compose the framework's
  component configs, load with caarlos0/env, APP_* app fields / EINHERJAR_*
  framework fields) and a Config & .env.example discipline (every env var the
  config reads is documented in .env.example, kept in lock-step).
- main.go now shows the `_ "github.com/joho/godotenv/autoload"` blank import,
  previously omitted. The assembly file is renamed launcher.go -> wire.go.
- Migrations and seeding removed from the documented scaffold — developer
  choices, not framework conventions. Re-synced against iron-dough-api / pei-api.

Version:
- Badge and serverVersion const were stale at v0.1.0; both now v1.0.0.

Docs:
- README (eleven tools, eleven validation rules) and CHANGELOG updated.

No new dependencies. The wire conventions are embedded at build time
(//go:embed builtins/README.md) and the new tool and rules are compiled in, so a
deployment must be rebuilt to serve them; a server still running the v0.2.0
binary keeps serving the old conventions until redeployed.

Reviewed-on: #2
Co-authored-by: Rene Nochebuena Guerrero <rene@nochebuena.dev>
Co-committed-by: Rene Nochebuena Guerrero <rene@nochebuena.dev>
2026-08-07 12:22:14 -06:00

143 lines
9.2 KiB
Markdown
Raw Blame History

# 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).
---
## [1.0.0] — 2026-08-07
The MCP reaches **v1.0.0**, aligned with the v1.0.0 framework. The headline is the
canonical application **scaffold**: the one opinionated starting point so an AI no longer
hand-rolls `main.go` and the launcher when creating a service from zero.
### Added
- **`get_scaffold` tool.** Returns the canonical minimum application scaffold as
ready-to-write files, with import paths filled from a `module` argument: a clean `main.go`
(godotenv autoload + `wire.Run()`), `internal/wire/wire.go` (the launcher assembly), a
composed `internal/config/config.go`, a health feature hook, and `.env.example`.
- **Three `validate_snippet` rules** (now eleven total), with a rules test suite:
`main.dirty` (the launcher/components built in `main` instead of `internal/wire`),
`main.no-godotenv-autoload` (a wire-convention `main` that never loads `.env`), and
`config.raw-getenv` (reading a framework `EINHERJAR_*` var via `os.Getenv` instead of
composing the component's `Config` type).
- **Config conventions in the `wire` builtin.** A `Config` section (compose the framework's
component configs, load with `caarlos0/env`, `APP_*` for app-owned fields, `EINHERJAR_*`
for framework ones) and a **Config & .env.example** section: every env var the config
reads must also be documented in `.env.example`, kept in lock-step.
### Changed
- **`wire` builtin re-synced to the current gold standards** (`iron-dough-api`, `pei-api`):
`main.go` now shows the `_ "github.com/joho/godotenv/autoload"` blank import (previously
omitted, so the AI produced a `main` that never loaded `.env`); the assembly file is
`wire.go` (was `launcher.go`).
- **Version alignment.** The README badge and `serverVersion` were stale at `v0.1.0`; both
now read `v1.0.0`.
### Removed
- **Migrations and seeding from the `wire` builtin.** How migrations run and how the first
admin is seeded (via code, a DB team, an endpoint, a webhook, …) is the developer's
choice — it belongs to no Einherjar module and is not a hard convention, so it is out of
the scaffold and the documented conventions.
## [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.
---
## [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 |
---
## [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
Reference in New Issue View Git Blame Copy Permalink