feat: add scoring module + Bayesian inertia test - #8
Merged
Conversation
robotrocketscience
added a commit
that referenced
this pull request
May 9, 2026
…dy for PR
Closes the mcp-builder audit of src/aelfrice/mcp_server.py started this
session. Resolves both CRITICAL findings, all six MAJOR findings, and
five of the eight MINOR findings. The deferred minors are documented
in this gate body for triage in follow-up issues.
## Commits in scope (10 atomic + 1 phase-1 gate before this)
Phase 1 — server is startable and discoverable
9adca85 feat(mcp): aelf mcp subcommand + python -m fallback
904bfb0 feat(mcp): docstrings on all 12 wrappers + AST regression guard
455eaac docs(mcp): document `aelf mcp` entrypoint + fix stale refs
46df710 gate: phase 1
Phase 2 — well-formed
a7576ad feat(mcp): annotations on every @mcp.tool
232d8ab feat(mcp): instructions= overview + 9-vs-12 stale comment fix
5f21c29 fix(mcp): tool_lock structured error vs AssertionError
Phase 3 — input/output discipline
6c6bf6c feat(mcp): Pydantic Field constraints via Annotated
174d245 feat(mcp): cursor pagination on tool_locked
7f04675 feat(mcp): response_format=markdown on read tools
Phase 4 — wrapper-layer testing
0214c17 test(mcp): wrapper-layer tests via static AST + fastmcp shim
## Verification
- pytest 76/76 passing across MCP test files (40 prior + 36 new):
test_mcp_server.py, test_mcp_lock_via_worker.py,
test_mcp_wrapper_layer.py, test_cli_mcp.py
- aelf --help: 'mcp' subcommand visible with help string
- aelf mcp (no [mcp] extra): exits 1 with actionable stderr
- Static AST guards: docstrings, annotations, instructions=, store
lifetime, no print()-to-stdout, all green
- fastmcp shim test: 12 tools register, all with full annotations,
read-only / destructive sets match expected
- Discretion grep: clean (only mentions Claude Code/Desktop, both
pre-existing on main as the intended MCP host targets)
## Audit findings closure
CRITICAL #1 Server unstartable → CLOSED (Phase 1 C1)
CRITICAL #2 Empty tool descriptions → CLOSED (Phase 1 C2)
MAJOR #3 No tool annotations → CLOSED (Phase 2 M1)
MAJOR #4 No Pydantic input validation → CLOSED (Phase 3 I1)
MAJOR #5 No server instructions= → CLOSED (Phase 2 M2)
MAJOR #6 No README/docs MCP setup section → CLOSED (Phase 1 C3)
MAJOR #7 Registration layer untested → CLOSED (Phase 4)
MAJOR #8 tool_lock hard assert → CLOSED (Phase 2 M4)
MINOR #11 No response_format enum → CLOSED (Phase 3 I2)
MINOR #12 No pagination on aelf_locked → CLOSED (Phase 3 I3)
MINOR #13 Stale 9-vs-12 tools comment → CLOSED (Phase 2 M3)
## Deferred (file follow-up issues)
MINOR #1 Server name "aelfrice" vs convention "aelfrice_mcp"
— backwards-compat break, not load-bearing. Defer.
MINOR #6 Sync handlers (no async def) — defensible for SQLite,
revisit if/when an async I/O dep lands.
MINOR #14 Polymorphic tool_onboard (3 input shapes in one tool)
— design call. Re-evaluate after host telemetry.
MINOR #15 Untyped fastmcp cast `_FastMCP: Any` — fastmcp lacks
stubs upstream. Pragmatic; revisit when stubs ship.
## Behavior changes worth flagging in PR description
- `tool_locked` return shape: ADDED keys total/has_more/next_offset.
Existing keys (kind/n/locked) preserved. Callers that consumed
`n` as "total locks across all locks" should switch to `total`.
- `tool_locked` returns first 50 by default instead of all locks. Tests
on stores with <50 locks behave identically.
- `tool_lock` returns lock.error dict (with `error` field) instead of
raising AssertionError on empty derivation. Callers that grep for
AssertionError need to update; callers that check `out["kind"]` are
fine.
## Blockers (require user decision before next phase)
- [user] Open PR? Branch is local-only on `feat/mcp-server-properly-built`.
Need a `git push -u github feat/mcp-server-properly-built` to land it,
then `gh pr create`. Not done by this gate.
- [user] File the four deferred-minor follow-up issues now or after
PR merge?
- [user] Resume parked feat/aelf-upgrade-imperative work next session?
That branch has no commits but the worktree state is captured in the
end-of-session handoff.
Open questions: (none)
Rollback:
- Whole branch: never merged → just delete `feat/mcp-server-properly-built`.
- Per-phase: `git revert <phase-commit-range>` (see commit list above).
robotrocketscience
added a commit
that referenced
this pull request
May 9, 2026
…dy for PR
Closes the mcp-builder audit of src/aelfrice/mcp_server.py started this
session. Resolves both CRITICAL findings, all six MAJOR findings, and
five of the eight MINOR findings. The deferred minors are documented
in this gate body for triage in follow-up issues.
## Commits in scope (10 atomic + 1 phase-1 gate before this)
Phase 1 — server is startable and discoverable
9adca85 feat(mcp): aelf mcp subcommand + python -m fallback
904bfb0 feat(mcp): docstrings on all 12 wrappers + AST regression guard
455eaac docs(mcp): document `aelf mcp` entrypoint + fix stale refs
46df710 gate: phase 1
Phase 2 — well-formed
a7576ad feat(mcp): annotations on every @mcp.tool
232d8ab feat(mcp): instructions= overview + 9-vs-12 stale comment fix
5f21c29 fix(mcp): tool_lock structured error vs AssertionError
Phase 3 — input/output discipline
6c6bf6c feat(mcp): Pydantic Field constraints via Annotated
174d245 feat(mcp): cursor pagination on tool_locked
7f04675 feat(mcp): response_format=markdown on read tools
Phase 4 — wrapper-layer testing
0214c17 test(mcp): wrapper-layer tests via static AST + fastmcp shim
## Verification
- pytest 76/76 passing across MCP test files (40 prior + 36 new):
test_mcp_server.py, test_mcp_lock_via_worker.py,
test_mcp_wrapper_layer.py, test_cli_mcp.py
- aelf --help: 'mcp' subcommand visible with help string
- aelf mcp (no [mcp] extra): exits 1 with actionable stderr
- Static AST guards: docstrings, annotations, instructions=, store
lifetime, no print()-to-stdout, all green
- fastmcp shim test: 12 tools register, all with full annotations,
read-only / destructive sets match expected
- Discretion grep: clean (only mentions Claude Code/Desktop, both
pre-existing on main as the intended MCP host targets)
## Audit findings closure
CRITICAL #1 Server unstartable → CLOSED (Phase 1 C1)
CRITICAL #2 Empty tool descriptions → CLOSED (Phase 1 C2)
MAJOR #3 No tool annotations → CLOSED (Phase 2 M1)
MAJOR #4 No Pydantic input validation → CLOSED (Phase 3 I1)
MAJOR #5 No server instructions= → CLOSED (Phase 2 M2)
MAJOR #6 No README/docs MCP setup section → CLOSED (Phase 1 C3)
MAJOR #7 Registration layer untested → CLOSED (Phase 4)
MAJOR #8 tool_lock hard assert → CLOSED (Phase 2 M4)
MINOR #11 No response_format enum → CLOSED (Phase 3 I2)
MINOR #12 No pagination on aelf_locked → CLOSED (Phase 3 I3)
MINOR #13 Stale 9-vs-12 tools comment → CLOSED (Phase 2 M3)
## Deferred (file follow-up issues)
MINOR #1 Server name "aelfrice" vs convention "aelfrice_mcp"
— backwards-compat break, not load-bearing. Defer.
MINOR #6 Sync handlers (no async def) — defensible for SQLite,
revisit if/when an async I/O dep lands.
MINOR #14 Polymorphic tool_onboard (3 input shapes in one tool)
— design call. Re-evaluate after host telemetry.
MINOR #15 Untyped fastmcp cast `_FastMCP: Any` — fastmcp lacks
stubs upstream. Pragmatic; revisit when stubs ship.
## Behavior changes worth flagging in PR description
- `tool_locked` return shape: ADDED keys total/has_more/next_offset.
Existing keys (kind/n/locked) preserved. Callers that consumed
`n` as "total locks across all locks" should switch to `total`.
- `tool_locked` returns first 50 by default instead of all locks. Tests
on stores with <50 locks behave identically.
- `tool_lock` returns lock.error dict (with `error` field) instead of
raising AssertionError on empty derivation. Callers that grep for
AssertionError need to update; callers that check `out["kind"]` are
fine.
## Blockers (require user decision before next phase)
- [user] Open PR? Branch is local-only on `feat/mcp-server-properly-built`.
Need a `git push -u github feat/mcp-server-properly-built` to land it,
then `gh pr create`. Not done by this gate.
- [user] File the four deferred-minor follow-up issues now or after
PR merge?
- [user] Resume parked feat/aelf-upgrade-imperative work next session?
That branch has no commits but the worktree state is captured in the
end-of-session handoff.
Open questions: (none)
Rollback:
- Whole branch: never merged → just delete `feat/mcp-server-properly-built`.
- Per-phase: `git revert <phase-commit-range>` (see commit list above).
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Adds Beta-Bernoulli posterior_mean, type-specific exponential decay (with lock-floor short-circuit), and basic relevance. Bayesian-inertia property test verifies that high-evidence-mass beliefs absorb new evidence less than low-mass beliefs (Spearman rho < -0.5).
Test plan