spacewalk-mcp

A Connector for Claude and ChatGPT that lets the model open and drive a Spacewalk 3D chromatin viewer shown beside the conversation.

The vocabulary used here is defined in GLOSSARY.md; decisions are in docs/adr/.

Layout

• server/: a Cloudflare Worker, the MCP endpoint (/mcp).

• remote/: @aidenlab/spacewalk-remote, published to npm: the library that attaches a Viewer to a Room, and the wire protocol the Worker imports from it.

• roundtrip/: end-to-end tests of the Viewer page, built from ../spacewalk, against the local Worker.

The Viewer page itself is built and deployed from the spacewalk repo, which pins @aidenlab/spacewalk-remote (ADR 0003).

Related MCP server: BioNext-mcp

Requirements

• Node.js and npm

Getting started

npm install
cp server/.dev.vars.example server/.dev.vars   # local stand-ins for the Worker's secrets
npm run dev:server   # the local Worker, on http://localhost:8787

Checks

npm run typecheck
npm run test:run

Deploying

scripts/deploy-wizard.sh

The deploy wizard deploys the dev environment (the Worker spacewalk-mcp-dev and the Pages project spacewalk-viewer-dev) and walks you through connecting Claude desktop, claude.ai, ChatGPT desktop and ChatGPT web. It is re-runnable.

docs/dev-check.md is the cheat sheet for scripts/dev-check.mjs, which calls one tool on the dev Worker from the terminal: a smoke test without a Host.