<p align="center"> <img src="./assets/repo/Gemini_Generated_Image_v5uajdv5uajdv5ua.png" alt="stellar-raven — thermal neural interface" width="100%"> </p>

Stellar Raven

Remote MCP server on Cloudflare Workers exposing two tools, search and execute, over a unified catalog of Stellar ecosystem services and skills. Agents use search to discover capabilities, then call execute with JavaScript that runs in a Dynamic Worker isolate with no network access; service calls go through host-side adapters. The server instructions also include a generated source-family micro-map so agents can plan which catalog family should ground a question before searching.

Design: PLAN.md. Code-verified mechanics and operating limits: ARCHITECTURE.md.

Deployed as the Cloudflare worker stellar-raven-codemode at https://raven.stellar.buzz — the worker/service name deliberately keeps the codemode suffix even though the repo is stellar-raven.

Quickstart

Server URL:   https://raven.stellar.buzz        (live since 2026-07-02; alias: https://agents.stellar.buzz still works)
MCP endpoint: POST https://raven.stellar.buzz/mcp   (streamable HTTP)  # or https://agents.stellar.buzz/mcp
Health:       GET  /health          # service heartbeat
              GET  /health/skills   # last skill-retrieval canary verdict (503 = failing/never ran)

Local dev: use Node 24, run npm ci, populate .dev.vars, then npm run dev and point a client at http://localhost:8787/mcp. Note: wrangler dev does NOT hot-reload .dev.vars edits — restart it after changing them.

Connect

Add https://raven.stellar.buzz/mcp in an MCP client that supports streamable HTTP and OAuth (Claude, Cursor, or any compatible client). The Worker is its own OAuth authorization server and hands sign-in to WorkOS AuthKit; clients should discover and complete that flow automatically. Access tokens last 1 hour, and compatible clients refresh them automatically within a fixed 90-day authorization window before browser authorization is required again.

Operators can manage non-expiring, full-access named credentials in production OAUTH_KV:

npm run mcp-key -- create admin
npm run mcp-key -- rotate admin --out /tmp/stellar-raven-admin.credential
npm run mcp-key -- revoke admin

Names match [a-z][a-z0-9-]{0,31}. Create and rotate emit the credential once after the remote write; --out writes it with mode 0600. Send it as Authorization: Bearer <name>:<token>. Cloudflare KV changes can take 60 seconds or longer to propagate globally, so this is for infrequently changed internal keys, not immediate emergency revocation. See Cloudflare KV consistency.

Operational auth details live in ARCHITECTURE.md and research/auth-workos.md. Vulnerability reporting and researcher scope live in SECURITY.md.

Development

# use Node 24, matching CI
npm ci
npm run typecheck  # tsc
npm test           # vitest (offline; auth suite in test/auth.test.ts)
npm run typegen    # regenerate env.d.ts after wrangler.jsonc/.dev.vars changes

For local MCP testing, populate .dev.vars, run npm run dev, and point a client at http://localhost:8787/mcp. Restart wrangler dev after editing .dev.vars.

Observability

Structured JSON events (src/observability.ts) land in Workers Logs; traces are enabled with a custom codemode.execute span around each sandbox run (the Worker Loader isolate is not auto-instrumented). Both are queryable in the dash (Workers & Pages → Observability) or via the telemetry query API. Survey of the whole surface — pricing, query API, OTel export, GraphQL metrics: research/observability-cloudflare.md.

For cap/rate-limit reviews, start with ARCHITECTURE.md §7: it lists the shared execute sandbox limits, demo-only chat limits, MCP-only artifact/auth limits, and the log event names to query.

License

Apache-2.0 © 2026 Tyler van der Hoeven — except vendored third-party code in src/catalog/vendor/, which retains its upstream license. Ecosystem skill bodies are not vendored here at all: this repo commits only their pinned addresses (upstream commit + git blob hash) and fetches each file from its own upstream, verified, at build and read time. See THIRD-PARTY-NOTICES.md.