{
  "markdown": "# Meridian MCP\n\n**Dynamic task routing via orbital mechanics. Domain-agnostic — candidates can be tools, prompts, documents, products, or any routable entity.**\n\nPer request, an LLM (Llama-3.3-70B via [GitHub Models](https://github.com/marketplace/models)' free tier) emits *N* candidate routing entries. A deterministic classifier extracts a 9-scalar physics signature from each candidate's content alone — no curated lookup: `mass` (log-scaled body length × keyword count), `scope`, `independence`, `cross_domain` affinity (token-domain entropy across three star systems), `fragmentation`, `drag`, `dep_ratio` (max sibling Jaccard), `lagrange_potential`, `coherence_time` (g⁽¹⁾-style autocorrelation over the candidate's token stream — added in 3.1.0), plus orbital and optical parameters (semi-major axis, eccentricity, inclination, period, perihelion, aphelion, mean anomaly; wavelength, polarization, amplitude, phase). Six per-class scoring rules assign a celestial body class by argmax: `planet`, `moon`, `trojan`, `asteroid`, `comet`, or `irregular`.\n\nThe class-scoring rules:\n\n```\nscore_planet    = min(mass, scope, independence)^1.5\nscore_moon      = 2 · max(0, ½ - independence) · 𝟙[parent] · (1 - mass/2)\nscore_trojan    = dep_ratio · 𝟙[parent] · (1 - fragmentation)\nscore_asteroid  = 2.5 · max(0, 0.55 - mass) · scope · independence\nscore_comet     = drag · cross_domain · (1 - dep_ratio)\nscore_irregular = 0.85 · cross_domain · fragmentation\n\nclass(p) = argmax_c score_c(p)\n```\n\nOutput: a deterministically ranked list with `route_score`, full classification, and decision rule per candidate. Wire format: Model Context Protocol over stdio or Streamable HTTP. Stdio shim is ~5 KB. Tested with Claude Code, Cursor, Windsurf, Goose, Continue, Grok custom connectors, ChatGPT custom MCPs, and Claude.ai connectors.\n\n[![npm](https://img.shields.io/npm/v/meridian-orbital.svg)](https://www.npmjs.com/package/meridian-orbital)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n\n> **3.0 — renamed from `meridian-skills-mcp`.** The classifier was always domain-agnostic; the \"skills\" framing biased the LLM prompt toward AI-agent capabilities. v3 drops that framing across the prompt, code, branding, and npm name. Migration: `npm i -g meridian-orbital` (the old package is deprecated; both binaries are still named `meridian-mcp` / `meridian-mcp-http` so client configs keep working). The hosted HTTP MCP at `mcp.ask-meridian.uk/mcp` continues to work — URL unchanged.\n\n## Install (stdio — Claude Code / Cursor / Windsurf)\n\n```bash\nnpm install -g meridian-orbital\nclaude mcp add meridian meridian-mcp\n```\n\nSame install works in Cursor, Windsurf, Goose, Continue, and any MCP client that speaks stdio.\n\nYou'll need a GitHub personal access token with the `Models: read` permission (free tier). Generate one at https://github.com/settings/personal-access-tokens/new and export it:\n\n```bash\nexport MERIDIAN_GITHUB_TOKEN=github_pat_...\n```\n\n(The MCP also picks up plain `GITHUB_TOKEN` if you have one already in your environment.)\n\n## Use as a Grok connector\n\nA hosted Streamable-HTTP variant lives at **`https://mcp.ask-meridian.uk/mcp`** with full OAuth 2.1 + PKCE so it slots into any host that requires a connector URL — Grok's custom MCP connectors, ChatGPT custom MCPs, Claude.ai connectors. No npm install, no PAT entry from your side, no infra.\n\nIn Grok's \"Add custom connector\" dialog, paste these:\n\n| Field | Value |\n|---|---|\n| **Server URL** | `https://mcp.ask-meridian.uk/mcp` |\n| **Authorization endpoint** | `https://mcp.ask-meridian.uk/authorize` |\n| **Token endpoint** | `https://mcp.ask-meridian.uk/token` |\n| **Client ID** | `grok` |\n| **Client secret** | *(empty)* |\n| **Token auth method** | `none` (PKCE only) |\n| **Scopes** | `route_task` |\n\nWhen you click \"Authorize\" in Grok, it opens [`/authorize`](https://mcp.ask-meridian.uk/authorize) — a one-click confirmation page (no PAT pasting, no GitHub jargon). Inference runs against [GitHub Models](https://github.com/marketplace/models) using the operator's PAT, so end users see zero friction. Tokens last 1 hour and can be reauthorized any time.\n\nThe same URL works for **ChatGPT custom MCPs** and **Claude.ai connectors** — they speak the same MCP Streamable HTTP + OAuth 2.1 spec.\n\n### Self-hosting the HTTP variant\n\nIf you'd rather operate your own remote MCP, the package ships a Node binary:\n\n```bash\nnpx -y meridian-orbital meridian-mcp-http\n# → listening on http://0.0.0.0:3333/mcp · auth=pass-through · v3.1.0\n```\n\nOr via Docker (`MCP_MODE=http` flips the entrypoint):\n\n```bash\ndocker run --rm -p 3333:3333 -e MCP_MODE=http meridian-orbital\n```\n\nAuth modes:\n\n- **Pass-through (default).** Each call's `Authorization: Bearer …` is forwarded to GitHub Models. Users bring their own PAT.\n- **Shared gateway.** Set `MERIDIAN_GATEWAY_TOKEN` (what callers pass) + `MERIDIAN_GITHUB_TOKEN` (what the server uses for inference).\n\nThe hosted Worker variant additionally implements OAuth 2.1 + PKCE; the Node binary is bearer-only (suitable for stdio→HTTP bridges and tools like `curl`).\n\n## What it does\n\nSingle tool: **`route_task(task, limit?)`**.\n\n```\ninput: a natural-language task\n   ↓\nGitHub Models (Llama-3.3-70B) generates 5 candidates\n   ↓\nlocal orbital classifier\n   • derives physics: mass, scope, independence,\n     cross_domain, fragmentation, drag, dep_ratio\n   • assigns class: planet | moon | trojan |\n                    asteroid | comet | irregular\n   • computes star-system membership (forge / signal / mind),\n     parent candidate, Lagrange potential\n   ↓\noutput: ranked candidates with full bodies, classifications,\n        and decision rules\n```\n\nTypical call takes **5–15 seconds**. Each result ships its full markdown body so the caller agent can lift the candidate straight into its context window.\n\n## Configuration\n\n| Env var | Default | Purpose |\n|---|---|---|\n| `MERIDIAN_GITHUB_TOKEN` | falls back to `GITHUB_TOKEN` | GitHub PAT with `Models: read` scope. Required. |\n| `MERIDIAN_MODEL` | `meta/llama-3.3-70b-instruct` | Any [GitHub Models](https://github.com/marketplace/models) chat model |\n| `MERIDIAN_MODELS_ENDPOINT` | `https://models.github.ai/inference/chat/completions` | Override for self-hosted gateways |\n| `MERIDIAN_CANDIDATES` | `5` | How many candidates the LLM generates per call |\n| `MERIDIAN_TIMEOUT_MS` | `90000` | Abort the fetch after this many ms |\n| `PORT` | `3333` | (HTTP mode) port for `meridian-mcp-http` |\n| `HOST` | `0.0.0.0` | (HTTP mode) bind address |\n| `MERIDIAN_HTTP_PATH` | `/mcp` | (HTTP mode) endpoint path |\n| `MERIDIAN_GATEWAY_TOKEN` | *(unset)* | (HTTP mode) if set, switches auth from pass-through to shared-key gateway. Bearer must match this value; server uses its own `MERIDIAN_GITHUB_TOKEN` for inference. |\n\n## What changed in `2.0.0`\n\nThe `1.x` line called a Cloudflare Worker (`https://ask-meridian.uk/api/orbital-route`) that ran the LLM and orbital classifier server-side. That backend has been retired. `2.0.0`:\n\n- **Self-contained.** The orbital classifier runs in-process. The LLM call goes to GitHub Models directly. No backend dependency.\n- **Bring-your-own token.** Free GitHub tier, generous quota.\n- **Faster.** 5–15 s instead of 30–50 s (no extra network hop, GitHub's inference is quick).\n- **Same output shape.** Drop-in replacement; no agent prompt changes needed.\n\nTo keep using the closed-domain Python scorer + curated 88-entry corpus that shipped with `0.3.x`, pin to `meridian-skills-mcp@0.3.2`. To keep calling the now-defunct Cloudflare backend, pin to `1.0.1` (will fail with HTTP 405 on every call).\n\n## Web miniapp + the live remote MCP\n\nSame orbital classifier powers two front-ends served from `mcp.ask-meridian.uk`:\n\n- **[ask-meridian.uk/miniapp](https://ask-meridian.uk/miniapp)** — type a task, see the candidates orbit. Calls the live MCP at `mcp.ask-meridian.uk/v1/route`, same Llama-3.3-70B + classifier path the connector uses.\n- **[meridian.ask-meridian.uk/lens/](https://meridian.ask-meridian.uk/lens/)** — WebXR Vision Lab. Captured headset frames POST to `mcp.ask-meridian.uk/v1/vision` (GPT-4o-mini, operator-paid), candidates orbit anchored star systems in-view. Same backend as miniapp.\n\nBoth call the **first-party browser endpoint** `/v1/route` — Origin-allowlisted, operator-paid, no PAT pasting. The OAuth-gated `/mcp` endpoint (this section's \"Use as a Grok connector\" path) is unchanged.\n\n## Online learning loop\n\nThe browser endpoint `/v1/route` applies a fitted-correction layer on top of the heuristic ranking. Every time a user engages a candidate (planet click in lens, detail-panel open in miniapp, card click in vision-lab), the front-end POSTs to `/v1/feedback` and the worker runs **one pairwise-ranking SGD step** against the chosen candidate vs every other. Constant per-request cost (~1 ms), no GPU, no local execution.\n\n```\nuser click → /v1/feedback → KV → SGD step → updated weights → next /v1/route uses them\n```\n\n- `final_score = heuristic_route_score × (1 + tanh(K · w·x))` — bounded to [0, 2], so no individual candidate can be silently boosted beyond 2× heuristic.\n- 25-feature vector per candidate: 9 physics scalars (the 8 originals plus `coherence_time` added in 3.1.0) + 6 class one-hot + 3 star-system one-hot + 3 token-hit features + 4 ranking features. Stored under `FEATURE_VERSION=v2` in KV; bumping the version re-inits weights cleanly.\n- Cold start: `w = 0`, multiplier = 1, pure heuristic. Day 1 deployments don't need any training data.\n- The OAuth-gated `/mcp` path (Grok / ChatGPT / Claude.ai connectors) keeps deterministic heuristic ranking for reproducibility.\n- Two GitHub Actions cron jobs close the loop without organic traffic: `classifier-bootstrap.yml` (every 3 days, feeds labelled examples from a public HF benchmark into `/v1/feedback`) and `classifier-health.yml` (Mondays, posts recall@1 / @5 + model state to `landing/healthz.json`).\n\nRead-only model state: `GET https://mcp.ask-meridian.uk/v1/model-info`.\n\nFull architecture + the calibration journey that produced this design (the planet-bias bug, the two textbook physics frameworks we tried and abandoned, the v2 retune, the 81% recall@1 [95% Wilson CI 60%, 92%] finding on real labelled data): [blog post](https://ask-meridian.uk/blog/orbital-classifier-online-learning/).\n\n## License\n\nMIT — see [LICENSE](./LICENSE).\n",
  "bytes": 10381,
  "sha": "a2747e0a1c6c5ce5bcff75723a28333aec054d69fee72bca95f3016755b1805e",
  "repo_slug": "luuow/meridian-mcp",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_luuow_meridian_skills_78944c41/readme"
}