Skip to content

README.md

Latest commit

 

History

History
154 lines (109 loc) · 5.71 KB

README.md

File metadata and controls

154 lines (109 loc) · 5.71 KB

@razroo/parallel-mcp-server

npm license node

@razroo/parallel-mcp-server is a thin Model Context Protocol server on top of @razroo/parallel-mcp. It exposes the durable-orchestration core — runs, tasks, leases, context snapshots, the event log — as MCP tools that an agent can call over stdio.

If @razroo/parallel-mcp is the "engine", this package is the "steering column" that lets an MCP client drive it.

What it gives you

  • One MCP tool per public orchestrator method
  • A ready-to-run parallel-mcp-server stdio binary
  • A createParallelMcpServer(...) factory for embedding the server in your own process
  • Typed errors from the core bubble up as MCP isError tool results with the original error name preserved

Install

npm install @razroo/parallel-mcp-server

Requires Node.js >=22. Pulls in @razroo/parallel-mcp and @modelcontextprotocol/sdk.

Run as a stdio server

The package ships a binary that opens a SQLite store and speaks MCP over stdio:

# in-memory store, lost when the process exits
npx parallel-mcp-server

# durable SQLite file
PARALLEL_MCP_DB=./parallel-mcp.db npx parallel-mcp-server

Point your MCP client (Cursor, Claude Desktop, etc.) at that binary. For example in a Cursor MCP config:

{
  "mcpServers": {
    "parallel-mcp": {
      "command": "npx",
      "args": ["-y", "@razroo/parallel-mcp-server"],
      "env": {
        "PARALLEL_MCP_DB": "/absolute/path/to/parallel-mcp.db"
      }
    }
  }
}

Run as a Streamable HTTP server

The package also ships parallel-mcp-server-http, which serves the same tool surface over the MCP Streamable HTTP transport — useful for remote deployments where stdio is not an option.

PARALLEL_MCP_DB=./parallel-mcp.db \
PARALLEL_MCP_PORT=3333 \
PARALLEL_MCP_HOST=127.0.0.1 \
PARALLEL_MCP_TOKEN=some-shared-secret \
npx parallel-mcp-server-http

Environment variables:

  • PARALLEL_MCP_DB — SQLite filename (default :memory:)
  • PARALLEL_MCP_PORT — listening port (default 3333)
  • PARALLEL_MCP_HOST — bind address (default 127.0.0.1)
  • PARALLEL_MCP_PATH — MCP endpoint path (default /mcp)
  • PARALLEL_MCP_TOKEN — optional. When set, every request must include Authorization: Bearer <token> or the server responds 401.

MCP clients connect with new StreamableHTTPClientTransport(new URL('http://host:port/mcp')).

Embed in your own server

Stdio

import { createParallelMcpServer } from '@razroo/parallel-mcp-server'
import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js'

const handle = createParallelMcpServer({
  storeOptions: { filename: './parallel-mcp.db' },
  defaultLeaseMs: 30_000,
})

await handle.server.connect(new StdioServerTransport())

HTTP

import { createParallelMcpHttpServer } from '@razroo/parallel-mcp-server'

const handle = createParallelMcpHttpServer({
  storeOptions: { filename: './parallel-mcp.db' },
  port: 3333,
  host: '0.0.0.0',
  authToken: process.env.PARALLEL_MCP_TOKEN,
})

const { url } = await handle.listen()
console.log(`parallel-mcp MCP server listening at ${url}`)

Both factories accept an existing SqliteParallelMcpStore or ParallelMcpOrchestrator — useful if you want to share one store between an HTTP surface, a stdio surface, and in-process workers.

Tool reference

All tools accept JSON objects and return JSON-encoded orchestrator records. Errors from the core (DuplicateTaskKeyError, RunTerminalError, LeaseConflictError, LeaseExpiredError, MaxAttemptsExceededError, etc.) are surfaced as MCP error results with the error name in the message.

Runs:

  • create_run — { id?, namespace?, externalId?, metadata?, context? }
  • get_run — { runId }
  • cancel_run — { runId, reason? }
  • list_run_tasks — { runId }
  • list_run_events — { runId }

Tasks:

  • enqueue_task — { runId, kind, key?, priority?, maxAttempts?, retry?, input?, metadata?, contextSnapshotId?, dependsOnTaskIds? }
  • claim_next_task — { workerId, leaseMs?, kinds? }
  • mark_task_running — { taskId, leaseId, workerId }
  • pause_task — { taskId, leaseId, workerId, status: 'blocked' | 'waiting_input', reason? }
  • resume_task — { taskId }
  • complete_task — { taskId, leaseId, workerId, output?, metadata?, nextContext?, nextContextLabel? }
  • fail_task — { taskId, leaseId, workerId, error, metadata? }
  • release_task — { taskId, leaseId, workerId, reason? }
  • get_task — { taskId }

Leases:

  • heartbeat_lease — { taskId, leaseId, workerId, leaseMs? }
  • expire_leases — { now? } → { expiredTaskIds, count }

Context:

  • append_context_snapshot — { runId, payload, scope?, label?, taskId?, parentSnapshotId?, id? }
  • get_current_context_snapshot — { runId }

Scope

This package is deliberately a thin adapter. It is not an agent, a planner, or a scheduler. The assumed topology is:

  1. Your agent (an MCP client) calls these tools to enqueue work and claim tasks.
  2. Actual worker processes can either be other MCP clients calling claim_next_task / complete_task / fail_task, or they can consume @razroo/parallel-mcp directly in-process.
  3. The MCP surface and the in-process surface agree because they are the same orchestrator.

License

MIT, same as @razroo/parallel-mcp.
⚡