Development

See CONTRIBUTING.md for how to propose changes, and architecture.md for the design and project layout.

Testing

Tests use the built-in Node test runner (node:test) executed through tsx.

npm test          # offline: URI/search routing, RPC resilience, write gating, operational endpoints
npm run test:live # live (in-memory): every tool against a real Blurt RPC node
npm run test:http # live (HTTP E2E): every tool over the real Streamable HTTP transport
npm run docs:check # regenerate tool docs, validate links/npm README policy, build the docs site
npm run docs:site  # build the default VitePress documentation site
npm run smoke:http # optional deployment smoke against MCP_URL or localhost:3000/mcp
npm run smoke:package # optional npm package/tarball smoke after build
npm run pack:check # build + npm pack --dry-run
npm run test:all  # everything

Three layers, by design:

• Offline (test/uri, test/search, test/resilience, test/write, test/ops) — deterministic, no external network. Includes a resilience test that points the client at an unresponsive local mock to assert the RPC transport degrades gracefully (guards against the dblurt transport regression), write-gating tests (no write tools without a write context, capability profile resolution, default HTTP read-only behavior and the explicit unsafe HTTP override), and operational endpoint tests (/healthz, /readyz, request logging), and package-readiness assertions (scoped name, license, bins, files). Runs in CI on every push.
• Live, in-memory (test/live) — connects an in-memory MCP client to the server and calls every tool against BLURT_RPC_URLS. Validates tool logic and @beblurt/dblurt integration.
• Live, HTTP E2E (test/http) — boots the real Express app on an ephemeral port and drives it through the actual Streamable HTTP transport + shared client. This is the path the in-memory client does not exercise, where transport/client bugs surface. Run after dependency or transport changes.

Documentation policy

• docs/ is the canonical Markdown source for the documentation website builds.
• npm run docs:site builds the project-pages artifact with its project-pages base.
• npm run docs:siteweb builds the independent public website artifact for https://mcp.blurt-blockchain.com/ with base /, plus llms.txt, llms-full.txt, robots.txt and sitemap.xml.
• The npm/GitLab README is a landing page and must use absolute links for non-anchor documentation links so navigation works from npm.
• docs/tools.generated.md is generated from the tool registry; do not edit it by hand.
• docs/llms.txt and docs/llms-full.txt are generated from canonical documentation sources; regenerate them with npm run docs:llms and do not edit them by hand.
• Run npm run docs:check after changing README/docs/tool descriptions. It regenerates tool docs, validates LLM retrieval files, validates local Markdown links and npm-safe README links, builds both documentation targets, then checks that generated docs are committed.
• The repository publishes the project-pages VitePress site from docs/ on main.

Releasing

Versioning follows Semantic Versioning and the changelog is generated from Conventional Commits using commit-and-tag-version.

npm run release:dry     # preview the bump + changelog without writing anything
npm run release         # auto-bump from commits, update CHANGELOG.md, create an annotated tag
npm run release:minor   # or force a specific bump
npm run release:major

git push --follow-tags origin main

feat: bumps the minor, fix:/perf: bump the patch, and a BREAKING CHANGE: footer bumps the major. The package is prepared for npm as @blurt-blockchain/blurt-mcp-server, but publication remains a separate maintainer-authorized action. See release/provenance notes.