From ce4d3d0d5242e16a42a8d7b20bba5e76ee8d436b Mon Sep 17 00:00:00 2001 From: nym21 Date: Wed, 5 Aug 2026 16:47:18 +0200 Subject: [PATCH] global: docs --- crates/brk/README.md | 4 ++++ crates/brk_bindgen/README.md | 12 +++++++++--- crates/brk_bindgen/src/generators/llm/mod.rs | 19 +++++++++++++++++++ crates/brk_cli/README.md | 2 ++ crates/brk_client/README.md | 4 ++++ crates/brk_mcp/README.md | 8 ++++++-- crates/brk_mcp/src/server.rs | 2 +- crates/brk_server/README.md | 2 ++ crates/brk_server/src/api/openapi/mod.rs | 2 ++ crates/vecdb_derive/Cargo.toml | 2 +- docs/ARCHITECTURE.md | 10 ++++++++++ docs/README.md | 13 +++++++++++++ modules/brk-client/README.md | 4 ++++ packages/brk_client/README.md | 4 ++++ website/llms-full.txt | 2 +- website/llms.txt | 8 ++++++++ website_next/llms-full.txt | 2 +- website_next/llms.txt | 8 ++++++++ 18 files changed, 99 insertions(+), 9 deletions(-) diff --git a/crates/brk/README.md b/crates/brk/README.md index cf0340153..222bd2e1a 100644 --- a/crates/brk/README.md +++ b/crates/brk/README.md @@ -57,6 +57,10 @@ brk = { version = "0.1", features = ["full"] } |-------|-------------| | [brk_client](https://docs.rs/brk_client) | Generated Rust API client | | [brk_bindgen](https://docs.rs/brk_bindgen) | Generate typed clients (Rust, JavaScript, Python) | +| [brk_mcp](https://crates.io/crates/brk_mcp) | Stateless, read-only MCP adapter for the BRK API | + +The official MCP endpoint is +[mcp.bitview.space](https://mcp.bitview.space/). It requires no authentication. **Internal** diff --git a/crates/brk_bindgen/README.md b/crates/brk_bindgen/README.md index f6bb8397e..b3fbae094 100644 --- a/crates/brk_bindgen/README.md +++ b/crates/brk_bindgen/README.md @@ -4,11 +4,14 @@ Code generation for BRK client libraries. ## What It Enables -Generate clients for Rust, JavaScript, Python, and LLMs from the OpenAPI specification and metric tree. Keeps every consumer in sync with available metrics and API endpoints without manual maintenance. +Generate clients for Rust, JavaScript, Python, LLMs, and MCP from the OpenAPI +specification and metric tree. Keeps every consumer in sync with available +metrics and API endpoints without manual maintenance. ## Key Features - **Multi-client**: Generates Rust, JavaScript, Python, and LLM clients +- **MCP catalog**: Generates the MCP tool manifest from the same OpenAPI operations - **OpenAPI-driven**: Extracts endpoints and schemas from the OpenAPI spec - **Metric catalog**: Includes all metric IDs and their supported indexes - **Type definitions**: Generates types/interfaces from JSON Schema @@ -24,7 +27,8 @@ let paths = ClientOutputPaths::new() .javascript("modules/brk-client/index.js") .python("packages/brk_client/brk_client/__init__.py") .llm("website") - .llm("website_next"); + .llm("website_next") + .llm_manifest("crates/brk_mcp/generated/manifest.json"); generate_clients(&vecs, &openapi_json, &paths)?; ``` @@ -36,7 +40,7 @@ generate_clients(&vecs, &openapi_json, &paths)?; | Rust | Typed API client using `brk_types`, metric catalog | | JavaScript | ES module with JSDoc types, metric catalog, fetch helpers | | Python | Typed client with dataclasses, metric catalog | -| LLM | Concise discovery and complete plain-text API references | +| LLM/MCP | Plain-text API references and the MCP tool manifest | Language clients include: - All REST API endpoints as typed functions @@ -45,6 +49,8 @@ Language clients include: The LLM client emits the standard discovery files and links to the live OpenAPI and series endpoints instead of duplicating their catalogs. +The official generated MCP catalog is served through the stateless, read-only +endpoint at [mcp.bitview.space](https://mcp.bitview.space/). ## Built On diff --git a/crates/brk_bindgen/src/generators/llm/mod.rs b/crates/brk_bindgen/src/generators/llm/mod.rs index 5a064286a..96e871f4e 100644 --- a/crates/brk_bindgen/src/generators/llm/mod.rs +++ b/crates/brk_bindgen/src/generators/llm/mod.rs @@ -17,6 +17,7 @@ use super::write_if_changed; mod manifest; const BASE_URL: &str = "https://bitview.space"; +const MCP_URL: &str = "https://mcp.bitview.space/"; pub fn generate_llm_clients( metadata: &ClientMetadata, @@ -86,6 +87,11 @@ fn render_llms(title: &str, version: &str, metric_count: usize, endpoints: &[&En - [Series catalog]({BASE_URL}/api/series)\n\ - [Interactive documentation]({BASE_URL}/api)\n\n\ Use OpenAPI for tool construction, `/api/series` for complete series metadata, and `llms-full.txt` for a readable reference.\n\n\ +## MCP\n\n\ +- Endpoint: {MCP_URL}\n\ +- Transport: Streamable HTTP\n\ +- Authentication: None\n\n\ +The MCP server is stateless and read-only. Its tools are generated from these OpenAPI operations.\n\n\ ## Clients\n\n\ - [JavaScript](https://www.npmjs.com/package/brk-client)\n\ - [Python](https://pypi.org/project/brk-client/)\n\ @@ -113,6 +119,7 @@ fn render_llms_full( .unwrap(); writeln!(output, "- Version: `{version}`").unwrap(); writeln!(output, "- Base URL: {BASE_URL}").unwrap(); + writeln!(output, "- MCP endpoint: {MCP_URL}").unwrap(); writeln!(output, "- Metrics: {metric_count}").unwrap(); writeln!(output, "- Operations: {}\n", endpoints.len()).unwrap(); writeln!( @@ -476,9 +483,21 @@ mod tests { .count(), 1 ); + assert!(output.contains("- MCP endpoint: https://mcp.bitview.space/")); assert!(output.contains("curl -s \"https://bitview.space/api/thing/\"")); } + #[test] + fn discovery_lists_the_official_mcp_endpoint() { + let first = endpoint("/api/thing/{id}", "GET"); + let endpoints = [&first]; + let output = render_llms("BRK", "v1", 12, &endpoints); + + assert!(output.contains("- Endpoint: https://mcp.bitview.space/")); + assert!(output.contains("- Transport: Streamable HTTP")); + assert!(output.contains("- Authentication: None")); + } + #[test] fn schema_renderer_keeps_required_fields_and_references() { let schema = serde_json::json!({ diff --git a/crates/brk_cli/README.md b/crates/brk_cli/README.md index 3940834a0..a45aa95b4 100644 --- a/crates/brk_cli/README.md +++ b/crates/brk_cli/README.md @@ -3,6 +3,8 @@ Run your own Bitcoin Research Kit instance. One binary, one command. Full sync in ~4-7h depending on hardware. ~44% disk overhead vs 250% for mempool/electrs. [bitview.space](https://bitview.space) is the official free hosted instance. +For AI clients, the official stateless, read-only MCP endpoint is +[mcp.bitview.space](https://mcp.bitview.space/). It requires no authentication. ## Requirements diff --git a/crates/brk_client/README.md b/crates/brk_client/README.md index 7f01420b3..a2562d8d6 100644 --- a/crates/brk_client/README.md +++ b/crates/brk_client/README.md @@ -4,6 +4,10 @@ Rust client for the [Bitcoin Research Kit](https://github.com/bitcoinresearchkit [crates.io](https://crates.io/crates/brk_client) | [docs.rs](https://docs.rs/brk_client) +AI clients can use the same API through the official stateless, read-only MCP +endpoint at [mcp.bitview.space](https://mcp.bitview.space/). No authentication +is required. + ## Installation ```toml diff --git a/crates/brk_mcp/README.md b/crates/brk_mcp/README.md index 6f16cd01b..649082419 100644 --- a/crates/brk_mcp/README.md +++ b/crates/brk_mcp/README.md @@ -4,6 +4,10 @@ exposes the generated OpenAPI operations as MCP tools and forwards every tool call to the configured public REST origin as a `GET` request. +The official public endpoint is +[mcp.bitview.space](https://mcp.bitview.space/). It is stateless, read-only, and +requires no authentication. + ## Caching model `brk_mcp` does not cache API responses or retain MCP sessions. Point it at the @@ -14,7 +18,7 @@ existing Cloudflare cache: MCP client -> brk_mcp -> Cloudflare-cached REST API -> BRK server ``` -Cloudflare does not need to cache the `/mcp` endpoint. The MCP catalog TTL is +Cloudflare does not need to cache the MCP endpoint. The MCP catalog TTL is only a standard client-side cache hint for the static discovery and tool-list metadata. @@ -39,7 +43,7 @@ fails at the transport layer. An explicit origin uses only that origin: brk_mcp http://127.0.0.1:3110 ``` -The Streamable HTTP endpoint is `http://127.0.0.1:3111/mcp` by default. If that +The Streamable HTTP endpoint is `http://127.0.0.1:3111/` by default. If that port is unavailable, the server tries each port through `3211`. The server supports MCP protocol version `2026-07-28`. diff --git a/crates/brk_mcp/src/server.rs b/crates/brk_mcp/src/server.rs index 6a1481e1a..8035ff829 100644 --- a/crates/brk_mcp/src/server.rs +++ b/crates/brk_mcp/src/server.rs @@ -111,7 +111,7 @@ pub fn router(api_bases: Vec, catalog: Catalog) -> Router { ); Router::new() - .route_service("/mcp", service) + .route_service("/", service) .layer(middleware::from_fn_with_state(state, gateway_guard)) } diff --git a/crates/brk_server/README.md b/crates/brk_server/README.md index cf6ba138c..8b7555ad1 100644 --- a/crates/brk_server/README.md +++ b/crates/brk_server/README.md @@ -6,6 +6,8 @@ HTTP API server for Bitcoin on-chain analytics. - **OpenAPI spec**: Auto-generated docs at `/api` with full spec at `/openapi.json` - **LLM-optimized**: Compact spec at `/api.json` for AI tools +- **MCP-ready**: The same OpenAPI operations are available through the official + stateless, read-only endpoint at [mcp.bitview.space](https://mcp.bitview.space/) - **Response caching**: ETag-based with LRU cache (1000 entries by default, configurable via `ServerConfig::cache_size`) - **Compression**: Brotli, gzip, deflate, zstd - **Static files**: Optional web interface hosting diff --git a/crates/brk_server/src/api/openapi/mod.rs b/crates/brk_server/src/api/openapi/mod.rs index 417666994..f3140a453 100644 --- a/crates/brk_server/src/api/openapi/mod.rs +++ b/crates/brk_server/src/api/openapi/mod.rs @@ -32,6 +32,7 @@ pub fn create_openapi() -> OpenApi { - **Series**: Thousands of on-chain time-series across multiple indexes (date, block height, etc.) - **Multiple formats**: JSON and CSV output - **LLM-optimized**: [`/llms.txt`](/llms.txt) for discovery, [`/api.json`](/api.json) compact OpenAPI spec for tool use (full spec at [`/openapi.json`](/openapi.json)) +- **MCP**: Stateless, read-only access to these operations at [mcp.bitview.space](https://mcp.bitview.space/), with no authentication required ### Quick start @@ -67,6 +68,7 @@ All errors return structured JSON with a consistent format: - [JavaScript](https://www.npmjs.com/package/brk-client) - [Python](https://pypi.org/project/brk-client/) - [Rust](https://crates.io/crates/brk_client) +- [MCP](https://mcp.bitview.space/) ### Links diff --git a/crates/vecdb_derive/Cargo.toml b/crates/vecdb_derive/Cargo.toml index 82544cb88..b66598573 100644 --- a/crates/vecdb_derive/Cargo.toml +++ b/crates/vecdb_derive/Cargo.toml @@ -18,5 +18,5 @@ syn = "3.0" quote = "1.0" [dev-dependencies] -vecdb = { workspace = true, features = ["derive", "pco"] } +vecdb = { path = "../vecdb", features = ["derive", "pco"] } tempfile = { workspace = true } diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md index a3496619b..feaad6d6b 100644 --- a/docs/ARCHITECTURE.md +++ b/docs/ARCHITECTURE.md @@ -7,6 +7,8 @@ blk*.dat ──▶ Reader ──┐ ├──▶ Indexer ──▶ Computer ──┐ RPC Client ──┤ ├──▶ Query ──▶ Server └──▶ Mempool ───────────────┘ + +MCP clients ──▶ MCP Adapter ──▶ Server ``` ## Components @@ -61,6 +63,14 @@ REST API exposing Query functionality: - ETag caching - mempool.space compatible endpoints +### MCP Adapter (`brk_mcp`) + +Provides stateless, read-only MCP tools generated from the server's OpenAPI +operations. It forwards tool calls to the configured REST origin, allowing a +Cloudflare-fronted API to keep serving cached responses. The official endpoint +is [mcp.bitview.space](https://mcp.bitview.space/) and requires no +authentication. + ## Data Flow **Initial sync:** diff --git a/docs/README.md b/docs/README.md index e24a1fa0d..9b940fa77 100644 --- a/docs/README.md +++ b/docs/README.md @@ -13,6 +13,8 @@ Open-source Bitcoin data toolkit that can parse blocks, index the chain, compute metrics, serve data and render it, all from a Bitcoin Core node. It combines what [Glassnode](https://glassnode.com) and [mempool.space](https://mempool.space) do separately into a single self-hostable package, with a built-in price oracle inspired by [UTXO Oracle](https://utxo.live/oracle/). [Bitview](https://bitview.space) is the official free hosted instance of BRK. +Stateless, read-only MCP access is available at +[mcp.bitview.space](https://mcp.bitview.space/), with no authentication required. ## Data @@ -42,6 +44,17 @@ Query metrics and blockchain data in JSON or CSV. No rate limit. [Documentation](https://bitview.space/api) · [JavaScript](https://www.npmjs.com/package/brk-client) · [Python](https://pypi.org/project/brk-client) · [Rust](https://crates.io/crates/brk_client) · [llms.txt](https://bitview.space/llms.txt) · [LLM-friendly schema](https://bitview.space/api.json) +### MCP + +Connect any Streamable HTTP MCP client to: + +```text +https://mcp.bitview.space/ +``` + +The server is stateless, read-only, and requires no authentication. Its tools +are generated from the same OpenAPI operations as the typed clients. + ### Self-host ```bash diff --git a/modules/brk-client/README.md b/modules/brk-client/README.md index 2567dca2c..516c472b8 100644 --- a/modules/brk-client/README.md +++ b/modules/brk-client/README.md @@ -6,6 +6,10 @@ Zero dependencies. [npm](https://www.npmjs.com/package/brk-client) | [API Reference](https://github.com/bitcoinresearchkit/brk/blob/main/modules/brk-client/docs/globals.md) +AI clients can use the same API through the official stateless, read-only MCP +endpoint at [mcp.bitview.space](https://mcp.bitview.space/). No authentication +is required. + ## Installation ```bash diff --git a/packages/brk_client/README.md b/packages/brk_client/README.md index a80683d16..6b4a2aeb9 100644 --- a/packages/brk_client/README.md +++ b/packages/brk_client/README.md @@ -6,6 +6,10 @@ Requires Python 3.9+. Zero dependencies. [PyPI](https://pypi.org/project/brk-client/) | [API Reference](https://github.com/bitcoinresearchkit/brk/blob/main/packages/brk_client/DOCS.md) +AI clients can use the same API through the official stateless, read-only MCP +endpoint at [mcp.bitview.space](https://mcp.bitview.space/). No authentication +is required. + ## Installation ```bash diff --git a/website/llms-full.txt b/website/llms-full.txt index 0738147e3..c8fff5bcb 100644 --- a/website/llms-full.txt +++ b/website/llms-full.txt @@ -4,6 +4,7 @@ - Version: `v0.3.6` - Base URL: https://bitview.space +- MCP endpoint: https://mcp.bitview.space/ - Metrics: 57886 - Operations: 97 @@ -2070,4 +2071,3 @@ curl -s "https://bitview.space/version" ### `Witness` `string[]` - diff --git a/website/llms.txt b/website/llms.txt index 2ab92a80e..f5d99003b 100644 --- a/website/llms.txt +++ b/website/llms.txt @@ -14,6 +14,14 @@ Use OpenAPI for tool construction, `/api/series` for complete series metadata, and `llms-full.txt` for a readable reference. +## MCP + +- Endpoint: https://mcp.bitview.space/ +- Transport: Streamable HTTP +- Authentication: None + +The MCP server is stateless and read-only. Its tools are generated from these OpenAPI operations. + ## Clients - [JavaScript](https://www.npmjs.com/package/brk-client) diff --git a/website_next/llms-full.txt b/website_next/llms-full.txt index 0738147e3..c8fff5bcb 100644 --- a/website_next/llms-full.txt +++ b/website_next/llms-full.txt @@ -4,6 +4,7 @@ - Version: `v0.3.6` - Base URL: https://bitview.space +- MCP endpoint: https://mcp.bitview.space/ - Metrics: 57886 - Operations: 97 @@ -2070,4 +2071,3 @@ curl -s "https://bitview.space/version" ### `Witness` `string[]` - diff --git a/website_next/llms.txt b/website_next/llms.txt index 2ab92a80e..f5d99003b 100644 --- a/website_next/llms.txt +++ b/website_next/llms.txt @@ -14,6 +14,14 @@ Use OpenAPI for tool construction, `/api/series` for complete series metadata, and `llms-full.txt` for a readable reference. +## MCP + +- Endpoint: https://mcp.bitview.space/ +- Transport: Streamable HTTP +- Authentication: None + +The MCP server is stateless and read-only. Its tools are generated from these OpenAPI operations. + ## Clients - [JavaScript](https://www.npmjs.com/package/brk-client)