AMB Relay MCP Server

An MCP (Model Context Protocol) server for querying educational resources from AMB (Allgemeines Metadatenprofil für Bildungsressourcen) Nostr relays.

Repository

The canonical repository lives on Nostr (NIP-34) — browse it on gitworkshop.dev, or clone with the ngit remote helper:

git clone nostr://laoc.xyz/relay.ngit.dev/amb-mcp

Mirrors: git.edufeed.org/edufeed/amb-mcp · github.com/edufeed-org/amb-mcp. Issues and PRs are welcome on any of the three — Nostr PRs arrive as pr/* branches.

Releases are tagged (v0.1.0, …) and listed in CHANGELOG.md.

Features

Query & Browse

• Cross-content full-text search (search_content) across educational resources, long-form articles, wikis, transferkiosk projects/measures, and NKBIP-01 scientific publications in one ranked call
• Semantic snippet passages from chunk re-ranking surfaced per result when the relay's re-ranking is active
• Full-text search with NIP-50
• Filter by publisher, creator, subject, resource type, educational level
• Browse available subjects, resource types, and educational levels
• Resolve author/organisation names to pubkeys (resolve_author) for author-scoped queries
• NIP-52 calendar event search with temporal, geohash, and hashtag filters
• SKOS controlled-vocabulary lookup and search (skos_*)
• Get individual resources by identifier
• Relay statistics and info

URL → Form-Prefill Metadata

• extract_metadata(url, variant, skosSchemes?) — fetch a public web page and produce a complete AMB/EKW form-prefill payload. Returns OpenGraph fallback by default; with ANTHROPIC_API_KEY set, an LLM grounded in the configured SKOS vocabularies fills SKOS-typed fields with concept IDs and per-field evidence quotes.
• Library export: import { extractMetadata } from 'amb-mcp/lib' for direct in-process use (e.g. SvelteKit server routes).

Signing & Publishing

• NIP-46 remote signing (bunker) with QR code connection flow
• Sign and publish arbitrary Nostr events
• Create and publish kind 0 (profile/metadata) events
• Create and publish kind 30142 (AMB educational resource) events
• NIP-42 relay authentication support
• Multi-user session isolation

Installation

bun install

Configuration

Copy .env.example to .env and configure:

cp .env.example .env

Environment variables

Name	Used by	Default	Description
AMB_RELAYS	all transports	wss://relay.edufeed.org	Comma-separated AMB relay URLs. Queried by every content tool (search_content, search_resources, get_resource, browse_*, resolve_author, relay_stats) and used as default publish targets for the signing tools.
AMB_EXTRA_RELAYS	all transports	(empty)	Comma-separated AMB relay URLs that are selectable but not searched by default. search_content, search_resources, and get_resource accept a relays parameter naming relays from AMB_RELAYS ∪ AMB_EXTRA_RELAYS (anything else is rejected); list_relays advertises both groups as defaultRelays/extraRelays. Use this to expose alternative corpora (e.g. the OERSI and SODIX aggregation relays, wss://oersi.edufeed.org,wss://sodix.edufeed.org) on request without merging them into every search. Over HTTP this list also feeds the ?relays= connector parameter — see Choosing a connector's default relays.
AMB_AUTHOR_SETS	all transports	(empty)	Comma-separated naddr identifiers of NIP-51 follow sets (kind 30000). Loaded once at startup into the author directory served by list_known_authors; the returned pubkeys can then be passed to search_* tools as authors.
CALENDAR_RELAYS	all transports	wss://relay.edufeed.org	Comma-separated NIP-52 calendar relay URLs for search_calendar_events. The AMB relay serves calendar events itself, so the default is the same relay; set this only for split deployments with a dedicated calendar relay.
CALENDAR_AUTHOR_SETS	all transports	(empty)	Same as AMB_AUTHOR_SETS, but for the calendar author directory served by list_calendar_authors.
EDUFEED_APP_BASE_URL	all transports	(unset)	Frontend base URL (no trailing slash, e.g. https://app.edufeed.org). When set, results from search_content, search_resources, get_resource, and search_calendar_events include a url field pointing at the edufeed-app viewer page (<base>/<naddr>) so LLM clients can render direct links. Unset means no url field.
SERVER_PRIVATE_KEY	src/index.ts (+ discovery scripts)	required for Nostr transport	Nostr private key (nsec or hex) that is the server's own ContextVM identity. The derived pubkey is what clients connect to via cvmi use <pubkey>. Not read by the stdio or HTTP transports.
RELAYS	src/index.ts (+ discovery scripts)	wss://relay.contextvm.org, wss://cvm.otherstuff.ai	Comma-separated relay URLs for ContextVM transport announcements and request/response traffic. Not read by the stdio or HTTP transports.
ANTHROPIC_API_KEY	extract_metadata	(unset)	Enables LLM-grounded SKOS field extraction. When unset the tool degrades gracefully to OpenGraph/JSON-LD-only output.
ANTHROPIC_MODEL	extract_metadata	claude-sonnet-4-6	Override the Anthropic model used for extraction.
SKOS_SCHEMES	extract_metadata	(unset)	JSON map { "<form-field>": "<scheme-uri>" } of default vocabularies used when the caller does not pass skosSchemes explicitly.
VOCAB_RELAYS	extract_metadata	falls back to AMB_RELAYS	Relays used to resolve naddr1… SKOS scheme identifiers to relay-hosted vocabularies.
SCHEME_NADDR_*	extract_metadata	(unset)	Per-vocabulary naddr overrides (e.g. SCHEME_NADDR_HCRT, SCHEME_NADDR_SCHULFAECHER) mapping well-known scheme URIs to relay-hosted SKOS vocabularies. See .env.example for the full list.
HTTP_*, OAUTH_*	src/http.ts only	see below	HTTP bind and OAuth resource-server settings — documented under Option 4.
EMBED_TOKEN	docker-compose.yml only	(unset)	Token for the embedding service used by the bundled local test relay. Not read by the server itself.

Usage

Option 1: Add to Claude Code (Recommended)

claude mcp add amb-relay -- bun run /path/to/amb-mcp/src/stdio.ts

This uses the default public relay (wss://relay.edufeed.org). To point at another relay — e.g. the local docker relay from Development — add -e AMB_RELAYS=ws://localhost:3337.

Option 2: Run with cvmi (ContextVM)

Start the server:

cvmi serve -- bun run src/stdio.ts

Connect from another machine:

cvmi use <server-pubkey>

Option 3: Run standalone with Nostr transport

bun run src/index.ts

Option 4: Run with Streamable HTTP transport

For web-based MCP clients (Claude.ai connectors, MCP Inspector, custom browser apps):

bun run src/http.ts   # dev
node dist/http.js     # production (after `npm run build`)

Variable	Default	Description
HTTP_PORT	3000	Port to bind.
HTTP_HOST	0.0.0.0	Bind host. Use 127.0.0.1 to limit to a local proxy.
HTTP_ALLOWED_HOSTS	(unset)	Comma-separated Host allow-list. Enables DNS-rebinding protection when set.
HTTP_ALLOWED_ORIGINS	(unset)	Comma-separated Origin allow-list.
OAUTH_ISSUER	https://auth.edufeed.org/realms/edufeed	OIDC issuer whose tokens are accepted.
OAUTH_AUDIENCE	amb-mcp	Required aud claim in access tokens.
OAUTH_JWKS_URI	<issuer>/protocol/openid-connect/certs	JWKS endpoint for token signature verification.
OAUTH_RESOURCE_URL	https://mcp.amb.edufeed.org/mcp	Public resource URL advertised in the OAuth protected-resource metadata document.

Authentication model: the HTTP transport is an OAuth 2.0 resource server.

• A request without an Authorization header gets an anonymous read-only session (mcp:read): search, get, browse, resolve, SKOS lookups.
• A request with a valid JWT (issued by OAUTH_ISSUER for audience OAUTH_AUDIENCE) is granted the token's scopes: mcp:read and/or mcp:extract (the budget-spending extract_metadata tool). An invalid token is rejected with 401.
• Write/signing tools are never exposed over HTTP — they are only available on the stdio and Nostr transports. Insufficient scope means the tool is simply absent from tools/list.

The server exposes:

• POST /mcp — JSON-RPC requests (initialize, tool calls, etc.)
• GET /mcp — server-push SSE stream for the current session
• DELETE /mcp — terminate the current session
• GET /healthz — unauthenticated liveness probe

Example handshake with curl:

# 1. initialize (anonymous = read-only session), capture the Mcp-Session-Id response header
curl -i http://localhost:3000/mcp -X POST \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"curl","version":"0"}}}'

# 2. reuse the session id for tools/list, tools/call, etc.
curl http://localhost:3000/mcp -X POST \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -H 'Mcp-Session-Id: <id-from-step-1>' \
  -d '{"jsonrpc":"2.0","id":2,"method":"tools/list"}'

# To use extract_metadata, add an OAuth token to the *initialize* request:
#   -H "Authorization: Bearer $ACCESS_TOKEN"
# (scopes are fixed at session init; a token on later requests does not upgrade the session)

Smoke-test with MCP Inspector:

npx @modelcontextprotocol/inspector http://localhost:3000/mcp

Choosing a connector's default relays

Most connector UIs (Claude.ai's "Add custom connector", for one) give you two fields: a name and a URL. So the URL is where a connection states which relays it wants searched by default:

https://mcp.amb.edufeed.org/mcp?relays=sodix
https://mcp.amb.edufeed.org/mcp?relays=amb-relay,sodix,oersi

The relays named in ?relays= become that session's default set — searched on every search_content / search_resources call. Every other relay the deployment serves stays in the extra set: list_relays still advertises it, and a tool call can still reach it through its own relays parameter. Without the parameter, the session uses the server's configured default set, exactly as before.

Names resolve against the relays the deployment already serves (AMB_RELAYS ∪ AMB_EXTRA_RELAYS). Each relay answers to three forms:

Form	Example
Full URL	wss://sodix.edufeed.org
Hostname	sodix.edufeed.org
First hostname label	sodix

A short label claimed by two relays is dropped rather than guessed at — use the hostname for those. The names are per deployment: list_relays on a plain session shows exactly which relays a server offers, and a rejected ?relays= lists every name it accepts. A name the deployment does not serve fails the initialize request with HTTP 400 and a JSON-RPC error listing the names it does accept; the connection is never silently pointed at the server default. Arbitrary relay URLs are not accepted, so a public endpoint cannot be used to make the server open WebSocket connections to hosts of the caller's choosing.

list_relays reports defaultRelaysSource: "connector-url" on such a session, so a model can tell a deliberately narrowed corpus from the deployment's standard one.

Public deployment

A managed instance is hosted at:

https://mcp.amb.edufeed.org/mcp

It serves three relays — amb-relay (wss://amb-relay.edufeed.org, the default), plus oersi and sodix as per-call extras — so …/mcp?relays=sodix gives a connector that searches the SODIX corpus by default. See Choosing a connector's default relays.

It speaks the same streamable-HTTP protocol as the local server. Read tools are public — a request with no Authorization header gets a read-only session (search/get/browse/resolve). The budget-spending extract_metadata tool requires a valid OAuth token carrying the mcp:extract scope; tokens are issued by the Keycloak realm out-of-band — ask the operator. The handshake is otherwise identical to the curl example above; just substitute the URL and drop the Authorization header for read-only use.

Available Tools

Tools are grouped into three profiles:

• Read — search, get, browse, resolve, SKOS lookups, calendar. Available on all transports; served anonymously over HTTP.
• Extract — extract_metadata. Over HTTP requires an OAuth token with the mcp:extract scope.
• Write — signer, publish, relay management, and SKOS vocabulary builder tools. Only exposed on the stdio and Nostr transports, never over HTTP.

search_content

Topic search across all content types in one ranked call — educational resources (30142), long-form articles (30023), wikis (30818), transferkiosk projects (30143), transferkiosk measures (30144), and NKBIP-01 scientific publications (30040 indices + 30041 sections — academic articles, books). Results are interleaved and ranked by semantic passage match; each carries the matched passage (snippet) when the relay's chunk re-ranking is active. This is the default entry point for natural-language questions.

Parameters:

Name	Type	Description
query	string	Free-text topic
types	string[]	Subset of ["resource","article","wiki","project","measure","publication"] (default: all)
language	string	Label language (default de)
since / until	number	Unix timestamp bounds
authors	string[]	Author pubkeys (hex)
limit	number	Max results, 1-250 (default 20)
community	string	Return content shared into this community (hex pubkey or npub)

Each result: { type, kind, title, url?, naddr?, snippet?, score?, ...type-specific }. For upcoming events on the same topic, follow up with search_calendar_events.

Facet-in-query syntax: relay-side facets ride inside query as NIP-50 field filters rather than as separate parameters — append them to the free-text term and the relay resolves them server-side. Examples: type:academic (publication display type), doi:10.1234/abcd.5678 (bare DOI, no doi: prefix in the stored value), keywords:<term> (topic words), or partOf:30143:<pubkey>:<d> (publications/measures that belong to a given project coord). These can be combined with a topic term, e.g. query: "seminardidaktik partOf:30143:<pubkey>:<d>".

search_resources

Search for educational resources using full-text search and metadata filters.

Parameters:

Name	Type	Description
query	string	Free-text search query
publisherName	string	Filter by publisher name
creatorName	string	Filter by creator/author name
subjectLabel	string	Filter by subject label (e.g., "Mathematik")
resourceTypeLabel	string	Filter by resource type (e.g., "Video", "Kurs")
educationalLevelLabel	string	Filter by educational level
language	string	Language for labels (default: "de")
authors	string[]	Filter by author pubkeys (hex) — e.g. from resolve_author or list_known_authors
since / until	number	Unix timestamp bounds on resource creation time
limit	number	Max results, 1-250 (default: 20)

get_resource

Retrieve a single piece of content by naddr, d-tag identifier, or event ID. An naddr from any search_content result resolves — resources, articles, wikis, projects, measures, and publications alike; non-resource kinds come back in the same shape as their search_content result ({ type, kind, title, ... }), not the full AMB resource shape. A bare identifier/eventId lookup (no naddr) always resolves the full educational-resource metadata (kind 30142), including creator/publisher and educational properties.

Parameters:

Name	Type	Description
identifier	string	Resource d-tag (URL identifier) — resolves kind 30142 only
author	string	Author pubkey for disambiguation
eventId	string	Direct Nostr event ID lookup — resolves kind 30142 only
naddr	string	NIP-19 naddr from a search_content result — preferred; works for any content type

Response shape (search_resources and get_resource)

Each returned resource includes the standard AMB fields plus:

• nostr.naddr — NIP-19 addressable identifier (kind=30142, pubkey, d-tag). Useful for any Nostr client.
• url — direct link to the edufeed-app page for this resource. Only present when EDUFEED_APP_BASE_URL is configured. LLM clients should cite this as a markdown link ([name](url)) when recommending the resource so users can open it.

resolve_author

Resolve an organisation or person name to candidate pubkeys using the relay's kind-0 author-profile index (NIP-50 search). This is the entry point for name-driven questions ("recent articles by Jörg Lohrer"): resolve the name, pick the best candidate, then pass its pubkey to search_content({ authors: [pubkey] }) or search_calendar_events. Returns up to limit candidates ranked by relevance.

Parameters:

Name	Type	Description
name	string	Org or person name to resolve
limit	number	Max candidates, 1-25 (default 10)

list_known_authors

List known educational-resource authors loaded from the configured follow sets (NIP-51 kind 30000, see AMB_AUTHOR_SETS). Returns names, pubkeys, and NIP-05 identifiers. Distinct from resolve_author, which searches the relay-wide profile index rather than hand-curated sets.

browse_subjects

List available subjects/topics with resource counts.

browse_resource_types

List available learning resource types (Video, Course, Worksheet, etc.).

browse_educational_levels

List available educational levels (Primary, Secondary, Higher Education, etc.).

relay_stats

Get relay information including name, description, and supported NIPs.

list_relays

List all AMB relays configured for the current session, split into defaultRelays (searched on every query) and extraRelays (selectable per call). defaultRelaysSource says whose choice the default set was — server-config, or connector-url when the connection URL named it via ?relays=. The write profile additionally exposes add_relay / remove_relay to adjust the session's relay set at runtime (per-session over HTTP; process-wide on stdio).

relay_list_get

Fetch a user's NIP-65 relay list (kind 10002). See NIP-65 Outbox Model below for the response shape.

SKOS vocabulary tools

Read tools for controlled vocabularies hosted as Nostr events or referenced by URI:

• skos_list_vocabularies — list vocabularies known to the server
• skos_get_vocabulary / skos_get_vocabulary_status — fetch a scheme with its concepts / check availability
• skos_get_concept — fetch a single concept with labels and relations
• skos_search — search concepts across vocabularies by label

The write profile adds a vocabulary builder suite (skos_create_vocabulary, skos_add_concept, skos_update_concept, skos_remove_concept, skos_set_relationship, skos_add_mapping, skos_import_turtle, skos_export_turtle, skos_delete_vocabulary) for authoring SKOS vocabularies and publishing them as Nostr events.

extract_metadata

Fetch one or more public web pages (or PDFs) and produce an AMB/EKW form-prefill payload. Returns OpenGraph/JSON-LD fallback by default; with ANTHROPIC_API_KEY set, an LLM grounded in the configured SKOS vocabularies fills SKOS-typed fields with concept IDs and per-field evidence quotes. Also available as a library export: import { extractMetadata } from 'amb-mcp/lib'.

Parameters:

Name	Type	Description
url	string	Public http(s) URL to extract (use urls for multiple sources)
urls	string[]	Multiple source URLs merged into one extraction (e.g. several PDFs)
variant	string	Form variant: amb (default), ekw (adds religious-education fields), konfi (adds Konfi-Arbeit fields)
skosSchemes	object	Map of form field → SKOS scheme URI, overriding SKOS_SCHEMES

Fetching is SSRF-aware (private/loopback ranges are blocked).

search_calendar_events

Search for NIP-52 calendar events (date-based 31922, time-based 31923). Supports temporal filters, geohash location filtering, and hashtag filtering.

Parameters:

Name	Type	Description
query	string	Free-text topic. Caveat: when combined with time/geo range filters the relay prioritises the range server-side and ignores this field — for "events about X next week" pass the time range and filter returned events by topic client-side.
startAfter / startBefore	number	Unix timestamp bounds for event start
endAfter / endBefore	number	Unix timestamp bounds for event end
geohash	string	Geohash prefix for location-based search
hashtags	string[]	Filter by hashtags
authors	string[]	Author pubkeys (hex)
kinds	number[]	Event kinds to query (default: [31922, 31923])
since / until	number	Unix timestamp bounds on event creation time
limit	number	Max results, 1-250 (default 20)

Each event carries naddr (NIP-19 addressable identifier) and, when EDUFEED_APP_BASE_URL is set, url (the edufeed-app viewer at <base>/<naddr>). Prefer citing url over sourcePage, since the viewer shows fuller event details.

list_calendar_authors

List known calendar event authors loaded from configured follow sets (NIP-51 kind 30000). Returns author names, pubkeys, and NIP-05 identifiers. Use the returned pubkeys with search_calendar_events(authors: [...]) to filter events by author.

---

Signing and Publishing

The MCP server supports signing and publishing Nostr events via NIP-46 remote signing (bunker).

Connecting a Signer

Option 1: QR Code Flow (Recommended)

1. Call signer_init to generate a nostrconnect:// URL and QR code
2. Scan the QR code with your bunker app (Amber, nsecBunker, etc.)
3. Call signer_await to wait for the connection to complete

Option 2: Bunker URL

If you have a bunker:// URL from your signer app, use signer_connect directly.

Option 3: Private Key (Development Only)

For testing, use signer_connect with an nsec and allowInsecure=true. Never use this in production.

Signer Tools

signer_init

Generate a QR code for connecting a signer app.

Parameters:

Name	Type	Description
relays	string[]	Relays for NIP-46 communication (defaults to AMB relays)
name	string	Client name shown in the bunker app
permissions	string[]	Requested permissions (e.g., ["sign_event:0", "sign_event:30142"])

Returns:

• sessionId - Session ID for signer_await
• nostrconnectUrl - The nostrconnect:// URL
• qrCode - ASCII QR code for terminal display

signer_await

Wait for a bunker app to connect after scanning the QR code.

Parameters:

Name	Type	Description
sessionId	string	Session ID from signer_init
timeout	number	Timeout in seconds (default: 120)

signer_connect

Connect directly using a bunker URL or private key.

Parameters:

Name	Type	Description
bunkerUrl	string	bunker:// URL from your signer app
nsec	string	Private key (nsec or hex) - development only
allowInsecure	boolean	Required when using nsec

signer_disconnect

Disconnect the current signer session.

signer_status

Check the current signer connection status.

Returns:

• connected - Whether a signer is connected
• userPubkey - The connected user's public key
• connectedAt - ISO timestamp of connection time

---

Publishing Tools

sign_event

Sign an unsigned Nostr event using the connected signer.

Parameters:

Name	Type	Description
kind	number	Event kind (e.g., 0 for metadata, 1 for note)
content	string	Event content
tags	string[][]	Event tags as array of arrays

publish_event

Publish a pre-signed Nostr event to relays.

Parameters:

Name	Type	Description
event	object	Signed Nostr event with id, pubkey, created_at, kind, tags, content, sig
relays	string[]	Relays to publish to (defaults to AMB relays)
useOutbox	boolean	Use NIP-65 outbox model for relay selection (default: true)

create_and_publish_metadata

Build, sign, and publish a kind 0 profile metadata event.

Parameters:

Name	Type	Description
name	string	Display name
about	string	Bio/description
picture	string	Avatar URL
banner	string	Banner image URL
nip05	string	NIP-05 identifier (e.g., user@domain.com)
lud16	string	Lightning address
website	string	Website URL
relays	string[]	Relays to publish to
useOutbox	boolean	Use NIP-65 outbox model for relay selection (default: true)

create_and_publish_resource

Build, sign, and publish a kind 30142 AMB educational resource event.

Parameters:

Name	Type	Description
identifier	string	Unique identifier (d-tag) for the resource
name	string	Resource name/title
description	string	Resource description
url	string	Resource URL
image	string	Image/thumbnail URL
type	string[]	Resource types (e.g., ["LearningResource", "VideoObject"])
inLanguage	string[]	Language codes (e.g., ["de", "en"])
about	object[]	Subject concepts with id and optional prefLabel
learningResourceType	object[]	Learning resource types from HCRT vocabulary
educationalLevel	object[]	Educational level concepts
creator	object[]	Content creators with name, type, id
publisher	object[]	Publishers with name, type, id
license	object	License with id (URL) and optional name
isAccessibleForFree	boolean	Whether the resource is free to access
datePublished	string	Publication date (ISO 8601)
relays	string[]	Relays to publish to
useOutbox	boolean	Use NIP-65 outbox model for relay selection (default: true)

---

NIP-65 Outbox Model

Publishing tools use the NIP-65 outbox model by default for intelligent relay selection:

1. Author's write relays - Fetched from kind 10002 events
2. Tagged users' read relays - For p-tagged mentions, fetches their read relays
3. Default relays - Falls back to configured AMB relays

This ensures events are delivered to relays where both the author publishes and where tagged users expect to receive events.

relay_list_get

Fetch a user's NIP-65 relay list (kind 10002).

Parameters:

Name	Type	Description
pubkey	string	Public key to fetch relay list for (defaults to connected signer)

Returns:

• pubkey - The queried public key
• readRelays - Array of relay URLs marked as read
• writeRelays - Array of relay URLs marked as write
• totalRead - Count of read relays
• totalWrite - Count of write relays

---

Available Resources

URI	Description
amb://schema	AMB JSON-LD schema
amb://vocabularies/subjects	Subject vocabulary
amb://vocabularies/resource-types	Learning resource types vocabulary
amb://vocabularies/educational-levels	Educational levels vocabulary
amb://relay-info	NIP-11 relay information

Deployment

The server has three entry points; pick the one that matches your client:

• src/index.ts (default CMD) — Nostr/ContextVM transport. No HTTP port. Clients reach it by addressing its pubkey on the configured ContextVM RELAYS. Requires SERVER_PRIVATE_KEY.
• src/stdio.ts — stdio transport for cvmi serve and Claude Code as a local subprocess.
• src/http.ts — Streamable HTTP transport on HTTP_PORT (default 3000). Use for web-based MCP clients. See Option 4 above for env vars and the handshake.

Prerequisites on the host

• Node ≥ 20 (or Bun ≥ 1.1) for runtime.
• Outbound WebSocket access to the configured AMB and ContextVM relays.
• Outbound HTTPS for the extract_metadata tool (target pages and, optionally, the Anthropic API).
• Network access to git.edufeed.org during install — the amb-nostr-converter dependency is fetched as a published tarball from the edufeed npm registry (see package.json).

Build & run

bun install              # or: npm install
bun run build            # tsc -> dist/
node dist/index.js       # production entry; uses Nostr transport

For development without a build step: bun run src/index.ts.

Identity & secrets

• SERVER_PRIVATE_KEY is the server's persistent Nostr identity. Losing or rotating it changes the pubkey clients use to address the server, so treat it as long-lived state. Mint one with nak key generate (or any Nostr keygen) and store it via your secret manager — never commit it.
• The matching pubkey is what users pass to cvmi use <pubkey>. Print it once after first start so operators can record it.
• ANTHROPIC_API_KEY, if used, should be scoped to this service; the extract_metadata tool will spend tokens on every call where SKOS grounding is requested.

State & persistence

The server itself is stateless on disk — all state lives on the configured relays. The only thing that needs to persist across restarts is the env file containing SERVER_PRIVATE_KEY. No volume is required for the MCP container.

Discovery

On startup with Nostr transport, the server publishes a ContextVM announcement to RELAYS. To remove an old announcement (e.g. after rotating the key or decommissioning), use scripts/unpublish-server.ts.

Operational notes

• Logging: plain stdout/stderr. Capture via your process supervisor (systemd journal, Docker logs, etc.).
• Healthcheck: the Nostr and stdio entry points have no HTTP healthcheck — liveness ≈ "process is up and the relay subscription has not errored", integrate at the supervisor level. The HTTP entry point exposes GET /healthz (unauthenticated) for probes.
• extract_metadata egress: the tool fetches arbitrary URLs supplied by callers. Fetching is SSRF-aware (private/loopback ranges blocked) but you should still consider running it behind an egress proxy if your homelab restricts outbound traffic.
• Resource footprint: small — a single Node process with a handful of WebSocket connections. No database, no cache directory.

Development

Run tests

bun run test        # vitest, no network needed

Test against local relay

docker-compose.yml in this repo starts a local AMB relay (with Typesense) on ws://localhost:3337 — it expects a sibling checkout of amb-relay at ../amb-relay for the image build:

docker compose up -d
AMB_RELAY_URL=ws://localhost:3337 bun run scripts/test-client.ts

Scripts

• scripts/ask.ts — pose a natural-language question to search_content and print the structured result an LLM client would receive
• scripts/test-client.ts — quick relay-client smoke test (relay info, queries, transforms)
• scripts/smoke-search-content.ts / scripts/smoke-extract-metadata.ts — live smoke tests against the dev relay
• scripts/unpublish-server.ts — remove server from public ContextVM discovery
• scripts/delete-announcements.ts — attempt to delete announcement events

Architecture

src/
├── index.ts          # Nostr/ContextVM transport entry point
├── stdio.ts          # Stdio transport entry point (for cvmi/Claude Code)
├── http.ts           # Streamable HTTP transport entry point (OAuth resource server)
├── session.ts        # Per-session MCP server factory (relay clients + tool profile)
├── server-info.ts    # Server name/version constants
├── authors.ts        # NIP-51 follow-set author directories
├── transport/
│   ├── http.ts       # Express app + StreamableHTTPServerTransport wiring
│   ├── auth.ts       # JWT verification (JWKS)
│   └── prm.ts        # OAuth protected-resource metadata document
├── relay/            # AMB relay client + NIP-50 filter builders
├── calendar/         # NIP-52 calendar filters + transforms
├── content/          # Multi-kind content transforms + snippet handling (search_content)
├── profiles/         # Kind-0 profile transforms (resolve_author)
├── skos/             # SKOS vocabulary client, parser, cache, Nostr loader
├── lib/              # extract_metadata library (fetch, PDF, LLM, vocab grounding)
├── signer/           # NIP-46 signing, publishing, NIP-65 relay lists, event builders
├── tools/            # One module per MCP tool (registered via tools/index.ts profiles)
├── resources/        # amb:// MCP resources (schema, vocabularies, relay info)
├── types/            # AMB TypeScript types
└── utils/            # Event → AMB resource transforms, community helpers

License

This is free and unencumbered software released into the public domain. See UNLICENSE for details.