docs(mcp): surface KV store on crates.io README + fix error mapping (follow-up to #185)#188
Merged
StefanSteiner merged 3 commits intoJul 10, 2026
Conversation
An invalid KV `store`/`key` (a disallowed byte or over the 512-byte limit) surfaced from the hyperdb-api layer as `Error::InvalidName` and fell through the catch-all arm to `INTERNAL_ERROR` — telling an LLM caller "server bug, give up" for something it supplied and can fix. Map `InvalidName` and `InvalidTableDefinition` to `INVALID_ARGUMENT`, which carries a self-correction suggestion; the human-readable message naming the offending byte or length is unchanged. `InvalidOperation` is deliberately left out: it is hyperdb-api caller-API misuse where the caller is this MCP's own Rust code, not the LLM, so it correctly stays `INTERNAL_ERROR`. A regression test locks in that distinction. Caught during the KV MCP smoke run.
Capture the manual, tool-driven smoke tests that exercise the eight `kv_*` tools against a live MCP server: CRUD/upsert, listing and discovery, value fidelity, destructive semantics, input validation (now INVALID_ARGUMENT), read-only mode, database routing/isolation, the LEFT JOIN enrichment pattern, the hidden backing table, and single-process atomicity. Includes a safety section: the persistent database may hold real data, so scratch names are `smoke_`-prefixed and every run ends by verifying the persistent DB is untouched. The existence-check safety rule is scoped to the target database — a bare `describe` inspects only the ephemeral primary and `status` never lists table names, so neither alone protects a persistent write. Cross-linked from DEVELOPMENT.md's Test section.
The key-value scratchpad tools shipped without documentation in the user-facing MCP README, the LLM-facing get_readme, or the workspace READMEs. Add coverage in the right places so an LLM told "remember X" considers kv_set instead of always reaching for CREATE TABLE: - hyperdb-mcp/README.md: new "### Key-Value Store" tool section; a "Table or key-value store?" decision rule in Queryable Memory for AI; the hyper://schema/kv Resources-table row; KV tools in the Features bullet; and the KV mutator/reader split across all three read-only enumerations (flag table, Allowed, Blocked). - src/readme.rs (get_readme): "KV store vs. a custom table" decision subsection; kv_pop lexicographic-order clarification; a describe persistent-DB signpost (status reports counts, not names); a back-link completing the bidirectional cross-link. - src/server.rs: kv_pop and kv_list_stores #[tool(description)] strings clarify lexicographic pop order and the no-store-registry behavior. - README.md (top-level): KvStore / AsyncKvStore Key Features bullet. Also fix a pre-existing false claim on the --read-only flag-table row (carried forward on a line this change edited): Hyper-format export is NOT disabled in read-only mode (export has no writable gate; it's a read-only file copy), matching the Read-Only "Allowed" list and the HyperMcpServer::new doc comment.
StefanSteiner
added a commit
that referenced
this pull request
Jul 10, 2026
…#188 (#189) fix(mcp): release KV README docs + INVALID_ARGUMENT error mapping (#188) #188 landed the human-facing KV store documentation (the crates.io README section that was missing from v0.6.0) and mapped caller-fixable identifier errors to INVALID_ARGUMENT. It merged with a docs(mcp): squash title, so release-please saw no releasable commit and cut no version. This empty fix(mcp): commit gives release-please a user-facing change to bump, so the already-merged #188 content ships as v0.6.1.
This was referenced Jul 10, 2026
Merged
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.
Summary
Follow-up to #185. Three commits that were finished locally but never
pushed before #185 merged, so they missed the v0.6.0 cut. Two are the
human-facing KV docs (the reason the crates.io page
shows no key-value store even though v0.6.0 ships the tools), and one is
a real error-mapping fix.
Why the docs were missing from v0.6.0
crates.io renders
hyperdb-mcp/README.md. In #185, the KV documentationlanded only in
hyperdb-mcp/src/readme.rs(the LLM-facingget_readmestring) — no commit in the merged PR touched
README.md. Soget_readmereturns full KV docs, but the rendered crate page has zero KV mentions.
This PR carries the
README.mdedits that were left behind.What's in this PR
Fixed
fix(mcp): caller-fixable argument errors now map toINVALID_ARGUMENT,not
INTERNAL_ERROR. An invalid identifier from thehyperdb-apilayer(e.g. a KV
store/keywith a disallowed byte or over the 512-byte limit)previously fell through to the catch-all
INTERNAL_ERROR, mislabeling acaller-fixable validation failure as a server bug.
InvalidName/InvalidTableDefinitionnow map toINVALID_ARGUMENT. Message textunchanged. (
error.rs+ 62 lines oferror_tests.rscoverage.)docs(mcp):README.md--read-onlyflag table no longer claimsHyper-format export is disabled. The row wrongly listed "Hyper-format
export" among disabled operations, contradicting both actual behavior
(
exporthas no read-only gate — a.hyperexport is a read-only filecopy and stays allowed) and the same doc's Read-Only "Allowed" list.
Docs
docs(mcp): surface the KV store across all human-facing doc surfaces.Adds the
### Key-Value Storetool section (8-tool table, example, keyproperties), the Features bullet, the
hyper://schema/kvResources row,and the mutator/reader split across the three read-only enumerations in
hyperdb-mcp/README.md; adds the top-levelREADME.mdKvStore/AsyncKvStorebullet. (Also touchesreadme.rs/server.rsdoc stringsfor the
kv_poplexicographic-order andkv_list_storesno-registrywording nudges.)
docs(mcp): add an on-demand KV smoke-test guide (SMOKE_TESTS.md).Verification
CI-exact toolchain (
1.97.0-aarch64-apple-darwin,HYPERD_PATHset):cargo fmt --all --check→ cleancargo clippy --workspace --all-targets --all-features -- -D warnings→ cleancargo test -p hyperdb-mcp --test error_tests→ 12 passedcargo test -p hyperdb-mcp --test readme_tests→ 3 passedcargo test -p hyperdb-mcp --test kv_tools_tests→ 11 passedNote for the maintainer
The
hyperdb-mcpCHANGELOG's[Unreleased]section still holds thev0.6.0 KV / TCP-keepalive bullets — release-please appears not to have
promoted
[Unreleased]→[0.6.0]for this crate at the v0.6.0 cut(there is no
## [0.6.0]heading onmain). This PR's two new### Fixedbullets are stacked above that content under
[Unreleased], so av0.6.1 release will sweep the whole section into the new version heading.