DataJourney MCP

A Gleam-based Model Context Protocol (MCP) server that exposes DataJourney interfaces over HTTP, Server-Sent Events (SSE), and WebSocket transports. It publishes official DataJourney documentation as an MCP resource and is ready to host additional DataJourney tools and prompts as they are implemented.

Features

• Documentation resource datajourney-documentation pointing to .
• HTTP JSON-RPC endpoint at POST /mcp for direct request/response flows.
• SSE transport at GET /mcp/sse (subscribe) and POST /mcp/sse (publish responses) for long-lived connections.
• WebSocket transport at GET /mcp/ws for bidirectional MCP sessions.

All transports share a single in-memory MCP server instance and a reusable SSE registry so multiple clients can connect simultaneously.

Getting Started

Install Gleam

Install the Gleam toolchain before running the project:

# macOS (Homebrew)
brew install gleam

# Linux (asdf)
asdf plugin add gleam

See for additional options and platform-specific guidance.

gleam deps download

Create a .env file (optional) to override defaults:

SECRET_KEY_BASE=some-long-secret
PORT=8000

Run the Mist HTTP server:

gleam run

You should see a log entry similar to DataJourney MCP server listening on port 8000. The health endpoint responds with GET /health.

MCP Testing Helpers

With the server running (gleam run), you can exercise MCP endpoints via the utility scripts in scripts/:

• ./scripts/read_resource.sh [resource_uri] streams a resources/read request. Override HOST, PORT, or REQUEST_ID via environment variables to target different deployments.
• ./scripts/list_resources.sh issues resources/list. Set CURSOR if you need to paginate through longer lists.

Talking to the MCP Server

SSE Transport

1. GET /mcp/sse to establish an event stream. The response includes an X-Conn-Id header.
2. POST /mcp/sse?id= with JSON-RPC payloads to send MCP messages. Responses are delivered both in the HTTP response body and streamed as SSE events named mcp-message.

WebSocket Transport

Upgrade a WebSocket connection at ws://localhost:8000/mcp/ws and exchange JSON-RPC payloads as plain-text frames. Each inbound message is forwarded to the MCP server; responses are emitted back to the client.

Project Layout

src/
├── datajourney_mcp.gleam   # Application entrypoint and Mist bootstrapping
├── mcp_server.gleam        # MCP server builder and documentation resource handler
├── router.gleam            # Mist request routing and transport glue
└── types.gleam             # Runtime/Startup context definitions

Development

gleam format
gleam test

Extend mcp_server.gleam with new tools, prompts, or resources to broaden the