mcp-core

Unified MCP Streamable HTTP 2025-11-25 transport, OAuth 2.1 Authorization
Server, lifecycle management, install automation, and shared embedding
daemon for the n24q02m MCP ecosystem.

mcp-core is the functional successor to the archived
mcp-relay-core. All crypto,
storage, OAuth, relay, and schema modules from mcp-relay-core ship under
the same paths in mcp-core (1:1 superset), so downstream MCP servers can
migrate with a pure import + dependency rename. See
docs/migration-from-mcp-relay-core.md
for the rename table.

Packages

All four packages share the same version (semantic-release.toml bumps all
three Python pyproject.toml files plus the npm package.json in lockstep).

What you get

n24q02m-mcp-core (Python) and @n24q02m/mcp-core (TypeScript)

Identical public API in both languages:

• crypto/ — ECDH P-256, AES-256-GCM, HKDF-SHA256 primitives.
  Cross-language test vectors guarantee Python and TypeScript produce the
  same ciphertext for the same input.
• storage/ — encrypted config file (config.enc) backed by PBKDF2
  600k + machine-id key derivation, plus session lock files and config
  resolver helpers.
• oauth/ — OAuth 2.1 Authorization Server building blocks: JWTIssuer
  (RS256), OAuthProvider (PKCE flow + relay session integration),
  SqliteUserStore for multi-user mode.
• relay/ — RelaySession, create_session, poll_for_result,
  send_message plus the EFF Diceware wordlist for passphrase generation.
• schema/ — RelayConfigSchema TypedDict that downstream servers use
  to declare their config form.
• transport/ — StreamableHTTPServer wrapper around FastMCP /
  @modelcontextprotocol/sdk Streamable HTTP transport, plus
  OAuthMiddleware (RFC 6750 + RFC 9728 compliant Bearer validation).
• lifecycle/ — LifecycleLock cross-platform file lock that prevents
  two server instances from binding the same (name, port) pair.
• install/ (Python only) — AgentInstaller that writes MCP server
  entries into Claude Code, Cursor, Codex, Windsurf, and OpenCode config
  files.

mcp-embedding-daemon

FastAPI HTTP server scaffold for the upcoming shared ONNX/GGUF embedding
backend. v0.1.0 alpha exposes:

• GET /health — returns {status, version}
• POST /embed — returns 501 with a roadmap link (backend wiring lands in
  the next release)
• POST /rerank — returns 501 with a roadmap link

CLI entry point: mcp-embedding-daemon --host 127.0.0.1 --port 9800.

mcp-stdio-proxy

Thin stdio-to-HTTP forwarder for agents that only support stdio MCP transport
(e.g., Antigravity). Reads JSON-RPC frames from stdin, POSTs them to a remote
MCP server, writes responses to stdout.

CLI entry point: mcp-stdio-proxy --url https://my-mcp.example.com/mcp --token <bearer>.
Falls back to MCP_CORE_SERVER_URL and MCP_CORE_SERVER_TOKEN env vars when
flags are not supplied.

Quick start (Python)

from mcp_core import RelaySession, create_session, decrypt
from mcp_core.transport.streamable_http import StreamableHTTPServer
from mcp_core.oauth import JWTIssuer
from mcp_core.transport.oauth_middleware import OAuthMiddleware
from fastmcp import FastMCP

mcp = FastMCP("my-server")

issuer = JWTIssuer("my-server")
issuer  # Use issuer.issue_access_token(sub) / verify_access_token(token)

middleware = [OAuthMiddleware(issuer=issuer, resource_metadata_url="http://127.0.0.1:9876/.well-known/oauth-protected-resource")]
server = StreamableHTTPServer(mcp, port=9876, middleware=middleware)
server.run()

Quick start (TypeScript)

import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js'
import { JWTIssuer } from '@n24q02m/mcp-core/oauth'
import { OAuthMiddleware, StreamableHTTPServer } from '@n24q02m/mcp-core/transport'

const server = new McpServer({ name: 'my-server', version: '0.0.0' })
const issuer = new JWTIssuer('my-server')
await issuer.init()

const middleware = new OAuthMiddleware({
  jwtIssuer: issuer,
  resourceMetadataUrl: 'http://127.0.0.1:9876/.well-known/oauth-protected-resource'
})

const http = new StreamableHTTPServer({ server, port: 9876, oauthMiddleware: middleware })
await http.connect()
// Then mount http.handleRequest(req, res) on your http.Server / Express / Hono.

Development

mise run setup            # install runtimes + deps + pre-commit hooks
bun install               # root TypeScript workspace install

# Python (per package)
cd packages/core-py
uv sync --group dev
uv run pytest
uv run ty check
uv run ruff check .

# TypeScript
cd packages/core-ts
bun run test
bun run check
bun run build

Spec

Architecture design lives in
claude-plugins/docs/superpowers/specs/2026-04-10-mcp-core-unified-transport-design.md.

License

MIT