nope-mcp (formerly amb-mcp)

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/nope-mcp · github.com/edufeed-org/nope-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.

Related MCP server: Nostr Tools for AI Agents

MCP Registry

server.json is the manifest nope-mcp publishes to the official MCP Registry as org.edufeed/nope-mcp, pointing at the https://mcp.edufeed.org/mcp remote. Its version always matches package.json (enforced by test/server-json.test.ts).

Publishing is done with the registry's mcp-publisher CLI after DNS-based domain verification of edufeed.org (the registry proves ownership of the org.edufeed namespace via a TXT record, not a secret the CLI holds) — there is no key to manage and no command embeds one.

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

• Grounded passage retrieval (search_passages) — answers a question from the corpus's fulltext with citations, scoped by a grimoire spell (kind 777) or inline scope; requires the indexer

• 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 'nope-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

Usage

Option 1: Add to Claude Code (Recommended)

claude mcp add nope-mcp -- bun run /path/to/nope-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`)

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 one of the OAUTH_AUDIENCE audiences) 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 / and POST /mcp — JSON-RPC requests (initialize, tool calls, etc.), same session map

• GET / and GET /mcp — server-push SSE stream for the current session

• GET / (plain browser request — no Mcp-Session-Id, no Accept: text/event-stream) — a small JSON info document (name, version, mcp, docs, transport) instead of the MCP 404; GET /mcp always behaves as an MCP session request

• DELETE / and DELETE /mcp — terminate the current session

• GET /.well-known/oauth-protected-resource / GET /.well-known/oauth-protected-resource/mcp — RFC 9728 protected-resource metadata for / and /mcp respectively, host-aware

• 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.edufeed.org/mcp?relays=sodix
https://mcp.edufeed.org/mcp?relays=amb-relay,sodix,oersi

(The previous host, https://mcp.amb.edufeed.org/mcp, keeps working unchanged — both accept the same ?relays= syntax.)

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:

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.edufeed.org/mcp

The previous URL, https://mcp.amb.edufeed.org/mcp, remains valid and serves the same deployment.

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.

The public endpoint is rate-limited per source IP at the edge (Traefik) — search_passages in particular embeds each query on the in-stack CPU service, so bursts are throttled. Normal interactive use is unaffected.

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.

Discovery vs. question intent. When search_passages is available (the indexer is configured), the two tools split by intent: search_content is for discovery — the user wants materials to browse ("finde/empfiehl Materialien zu X"), and you present the items as links. For a question the user wants answered from the sources ("wie/warum/was hilft bei X?"), use search_passages instead. When the indexer is not configured, search_content is the default entry point for natural-language questions.

Parameters:

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

If a selected relay times out or is unreachable, the response adds relaysIncomplete (the affected relays) and a warning — an empty or short result under that warning is not proof the corpus is empty. Absent those fields, every relay answered.

search_passages

Grounded RAG: retrieves the best-matching fulltext passages for a question and returns them with citations (source resource, page, heading, source URL) — answer the user from the passages and cite each source. This is the default tool for question-shaped queries; use search_content for discovery. Requires the indexer (INDEXER_ENDPOINTS); absent that config the tool is not registered.

Scope is required (the tool never runs an unscoped search) but usually trivial — with no source restriction, pass the content kinds. A restriction routes into scope: a metadata publisher (resolve_publisher finds the exact spelling) into search as a quoted field filter (publisher.name:"LEHRE LADEN"); a Nostr signer (resolve_author) into authors. Scope can also come from a published grimoire spell (kind 777) passed by nevent/event id; every response echoes the canonical spell for the scope so it can be published and reused. Spells may use $me/$contacts, resolved to the caller (pass me when the transport is anonymous).

Ranking. The indexer runs a Typesense hybrid search; search_passages requests vector weight alpha: 0.7 (the indexer's own default is the keyword-leaning 0.3, kept for the relay's rerank path), so the semantic rank leads and boilerplate keyword matches ("GRUNDSCHULE", "Kinder") stop winning. It over-fetches min(limit × 3, 100) chunks, then keeps at most two passages per document (event_coord), drops hits below 10 % of the top score, and returns the first limit. Phrase question as a topical statement naming subject and target group ("Friedenserziehung in der Grundschule: Einstieg in das Thema Frieden mit Kindern") rather than the user's literal sentence ("Wie kann ich …?"). A passage with only a snippet and no text is either license-gated or has no fulltext indexed yet.

Parameters:

Failure is explicit, never a silent unscoped search: empty_scope (the relay answered but nothing matched), relay_unreachable (the content relay did not answer — retry), spell_not_found, no_indexer, indexer_error.

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:

The subjectLabel / resourceTypeLabel / educationalLevelLabel filters are exact label matches (case-insensitive), not free text — a phrase that isn't a stored label returns 0. Put topic words in query; use browse_* to discover valid labels. publisherName / creatorName are exact too, but suggest near spellings (actorCandidates) on a zero-match.

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:

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.

search_content, search_resources, and search_calendar_events add relaysIncomplete + a warning when a selected relay timed out or was unreachable — under that warning an empty result is not proof the corpus is empty, so tell the user a source was unreachable and offer to retry. When every relay answers, neither field appears.

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:

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). A relays parameter (on search_content, search_resources, get_resource, search_passages) names relays from either group by full URL or short name — the hostname or first label (oersi, sodix, amb-relay), case-insensitive; an ambiguous label shared by two relays resolves only by its longer forms. 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 'nope-mcp/lib'.

Parameters:

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:

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:

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:

signer_connect

Connect directly using a bunker URL or private key.

Parameters:

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:

publish_event

Publish a pre-signed Nostr event to relays.

Parameters:

create_and_publish_metadata

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

Parameters:

create_and_publish_resource

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

Parameters:

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:

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

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.