meteora-docs-mcp 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Hero
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,119 @@
+# meteora-docs-mcp
+
+An [MCP](https://modelcontextprotocol.io) server that lets any AI assistant (Claude Code,
+Claude Desktop, Cursor, …) ask questions against **Meteora's official documentation AI
+assistant** at [docs.meteora.ag](https://docs.meteora.ag).
+
+It exposes a single tool:
+
+| Tool | Description |
+|------|-------------|
+| `ask_meteora_docs` | Ask a natural-language question about Meteora (DBC, DAMM v1/v2, DLMM, dynamic fees & fee sharing, Alpha Vault, fee scheduling, anti-sniper config, migration, SDK usage…). Returns the assistant's answer. |
+
+Under the hood it uses [CycleTLS](https://github.com/Danny-Dasilva/CycleTLS) (a Go TLS stack
+with a Chrome JA3 fingerprint) to pass Cloudflare bot detection — **no browser required**.
+
+---
+
+## For users — add it to your MCP client
+
+> Requires **Node.js ≥ 18**. The first run downloads a small platform binary (CycleTLS);
+> give it a few extra seconds.
+
+### Option A — from npm (recommended, once published)
+
+**Claude Code (CLI):**
+
+```bash
+claude mcp add meteora-docs -- npx -y meteora-docs-mcp
+```
+
+**Claude Desktop** — edit `claude_desktop_config.json`
+(Settings → Developer → Edit Config):
+
+```json
+{
+  "mcpServers": {
+    "meteora-docs": {
+      "command": "npx",
+      "args": ["-y", "meteora-docs-mcp"]
+    }
+  }
+}
+```
+
+**Cursor** — `.cursor/mcp.json` in your project (or the global one):
+
+```json
+{
+  "mcpServers": {
+    "meteora-docs": {
+      "command": "npx",
+      "args": ["-y", "meteora-docs-mcp"]
+    }
+  }
+}
+```
+
+Restart the client, then ask it something like *"Use meteora-docs to explain how DBC
+migration works."*
+
+### Option B — from source (no npm account needed)
+
+If you received this as a folder or `.zip`:
+
+```bash
+cd meteora-docs-mcp
+npm install
+```
+
+Then point your client at the absolute path of `index.js`:
+
+```json
+{
+  "mcpServers": {
+    "meteora-docs": {
+      "command": "node",
+      "args": ["C:/full/path/to/meteora-docs-mcp/index.js"]
+    }
+  }
+}
+```
+
+(Use forward slashes in JSON, even on Windows.)
+
+---
+
+## Quick smoke test (no MCP client)
+
+```bash
+npm install            # if you haven't
+node test-client.js "What is the Dynamic Bonding Curve?"
+```
+
+`test-client.js` spawns the server over stdio, runs the MCP handshake, and calls the tool
+once. (Included in the source tree; not published to npm.)
+
+---
+
+## Troubleshooting
+
+| Symptom | Fix |
+|--------|-----|
+| `Blocked by Cloudflare (HTTP 420)` | Meteora/Cloudflare changed their fingerprint detection. Update to the newest release (`npx -y meteora-docs-mcp@latest`). |
+| Antivirus / Gatekeeper flags the CycleTLS binary (`index.exe` on Windows, `index` / `index-mac*` on Linux/macOS) | That's the bundled CycleTLS Go binary. It's open-source; allow it, or use a machine where you can. |
+| `Could not obtain assistant token (JWT)` | Meteora changed their docs API path, or your network blocks `docs.meteora.ag`. |
+| Tool never appears in the client | Make sure nothing else prints to **stdout**; check the client's MCP logs (stderr) for `[meteora-docs-mcp] … running on stdio`. |
+
+---
+
+## For the author — publish & update
+
+See [PUBLISH.md](./PUBLISH.md) for step-by-step npm publishing and GitHub instructions.
+
+## License
+
+MIT — see [LICENSE](./LICENSE).
+
+> Unofficial. Not affiliated with or endorsed by Meteora. Answers come from Meteora's own
+> public documentation assistant; use at your own discretion.

package/index.js

@@ -0,0 +1,280 @@
+#!/usr/bin/env node
+/**
+ * meteora-docs-mcp — Model Context Protocol server for Meteora's docs AI assistant.
+ *
+ * Exposes one tool, `ask_meteora_docs`, that forwards a natural-language question to
+ * Meteora's official documentation assistant (docs.meteora.ag, served by Mintlify) and
+ * returns the answer. Uses CycleTLS (Go TLS stack with a Chrome JA3 fingerprint) to pass
+ * Cloudflare bot detection — no browser required.
+ *
+ * Transport: stdio (newline-delimited JSON-RPC 2.0). Works with Claude Code, Claude
+ * Desktop, Cursor, and any MCP-compatible client.
+ */
+
+'use strict';
+
+// ---------------------------------------------------------------------------
+// stdout HYGIENE — must run before anything else that might log.
+// The stdio transport writes JSON-RPC to process.stdout via process.stdout.write().
+// CycleTLS (and other deps) call console.log(), which also targets stdout and would
+// corrupt the protocol stream. Re-point every console.* method at STDERR so the only
+// thing on stdout is valid JSON-RPC.
+// ---------------------------------------------------------------------------
+const util = require('util');
+const toLine = (args) =>
+  args.map((a) => (typeof a === 'string' ? a : util.inspect(a, { depth: 4 }))).join(' ') + '\n';
+for (const method of ['log', 'info', 'debug', 'warn', 'trace']) {
+  console[method] = (...args) => process.stderr.write(toLine(args));
+}
+console.error = (...args) => process.stderr.write(toLine(args));
+
+const https = require('https');
+const crypto = require('crypto');
+const { McpServer } = require('@modelcontextprotocol/sdk/server/mcp.js');
+const { StdioServerTransport } = require('@modelcontextprotocol/sdk/server/stdio.js');
+const { z } = require('zod');
+const initCycleTLS = require('cycletls');
+
+const pkg = require('./package.json');
+
+const UA =
+  'Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/148.0.0.0 Safari/537.36';
+const JA3 =
+  '771,4865-4866-4867-49195-49199-49196-49200-52393-52392-49171-49172-156-157-47-53,0-23-65281-10-11-35-16-5-13-18-51-45-43-27-17513-21,29-23-24,0';
+
+// ---------------------------------------------------------------------------
+// Meteora assistant plumbing (ported from scripts/meteora-ask.js)
+// ---------------------------------------------------------------------------
+function nanoid16() {
+  const alphabet = 'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789';
+  const bytes = crypto.randomBytes(16);
+  let s = '';
+  for (let i = 0; i < 16; i++) s += alphabet[bytes[i] % 62];
+  return s;
+}
+
+function fetchJwt(docPath) {
+  return new Promise((resolve, reject) => {
+    https
+      .get(
+        {
+          hostname: 'docs.meteora.ag',
+          path: '/_mintlify/assistant/siteconfig',
+          headers: {
+            accept: '*/*',
+            'cache-control': 'no-cache',
+            referer: 'https://docs.meteora.ag/' + docPath,
+            'user-agent': UA,
+          },
+        },
+        (res) => {
+          let d = '';
+          res.on('data', (c) => (d += c));
+          res.on('end', () => {
+            const t = d.trim().replace(/^"|"$/g, '');
+            t && t.startsWith('eyJ')
+              ? resolve(t)
+              : reject(new Error('Could not obtain assistant token (JWT). Meteora may have changed its docs API.'));
+          });
+        }
+      )
+      .on('error', reject)
+      .setTimeout(10000, function () {
+        this.destroy(new Error('Timeout fetching assistant token'));
+      });
+  });
+}
+
+function parseSSE(raw) {
+  let answer = '';
+  let messageId = null;
+  const searches = [];
+  let usage = null;
+  for (const line of String(raw).split('\n')) {
+    if (line.startsWith('0:')) {
+      try {
+        answer += JSON.parse(line.slice(2));
+      } catch {
+        answer += line.slice(2);
+      }
+    } else if (line.startsWith('f:')) {
+      try {
+        const f = JSON.parse(line.slice(2));
+        if (f.messageId) messageId = f.messageId;
+      } catch {}
+    } else if (line.startsWith('9:')) {
+      try {
+        const t = JSON.parse(line.slice(2));
+        if (t.args && t.args.query) searches.push(t.args.query);
+      } catch {}
+    } else if (line.startsWith('d:')) {
+      try {
+        usage = JSON.parse(line.slice(2));
+      } catch {}
+    }
+  }
+  return { answer: answer.trim(), messageId, searches, usage };
+}
+
+// ---------------------------------------------------------------------------
+// CycleTLS lifecycle — one shared instance (the Go process is expensive to spawn),
+// lazily created and re-created if the transport dies.
+// ---------------------------------------------------------------------------
+let cycleTLSPromise = null;
+function getCycleTLS() {
+  if (!cycleTLSPromise) cycleTLSPromise = initCycleTLS();
+  return cycleTLSPromise;
+}
+function resetCycleTLS() {
+  const p = cycleTLSPromise;
+  cycleTLSPromise = null;
+  if (p) p.then((c) => { try { c.exit(); } catch {} }).catch(() => {});
+}
+
+async function askMeteora(question, docPath) {
+  const path = String(docPath || 'overview').replace(/^\//, '');
+  const jwt = await fetchJwt(path);
+  const cycleTLS = await getCycleTLS();
+
+  const body = JSON.stringify({
+    id: 'meteora',
+    messages: [
+      {
+        id: nanoid16(),
+        createdAt: new Date().toISOString(),
+        role: 'user',
+        content: question,
+        parts: [{ type: 'text', text: question }],
+      },
+    ],
+    fp: 'meteora',
+    currentPath: '/' + path,
+    _: jwt,
+  });
+
+  let res;
+  try {
+    res = await cycleTLS(
+      'https://leaves.mintlify.com/api/assistant/meteora/message',
+      {
+        body,
+        ja3: JA3,
+        userAgent: UA,
+        timeout: 60,
+        headers: {
+          accept: '*/*',
+          'accept-language': 'en-US,en;q=0.8',
+          'content-type': 'application/json',
+          origin: 'https://docs.meteora.ag',
+          referer: 'https://docs.meteora.ag/',
+          'sec-ch-ua': '"Chromium";v="148", "Brave";v="148", "Not/A)Brand";v="99"',
+          'sec-ch-ua-mobile': '?0',
+          'sec-ch-ua-platform': '"Windows"',
+          'sec-fetch-dest': 'empty',
+          'sec-fetch-mode': 'cors',
+          'sec-fetch-site': 'cross-site',
+          'sec-gpc': '1',
+          priority: 'u=1, i',
+        },
+      },
+      'post'
+    );
+  } catch (e) {
+    // The CycleTLS transport itself failed (process died / socket closed) — drop the
+    // instance so the next call respawns a fresh one.
+    resetCycleTLS();
+    throw new Error('CycleTLS request failed: ' + (e && e.message ? e.message : String(e)));
+  }
+
+  if (res.status === 420 || res.status === 403) {
+    throw new Error(
+      'Blocked by Cloudflare (HTTP ' +
+        res.status +
+        '). The JA3/TLS fingerprint may need updating — check for a newer meteora-docs-mcp release.'
+    );
+  }
+  if (res.status >= 400) {
+    throw new Error('Meteora assistant returned HTTP ' + res.status + ': ' + String(res.data || '').slice(0, 300));
+  }
+
+  return parseSSE(String(res.data || ''));
+}
+
+// ---------------------------------------------------------------------------
+// MCP server
+// ---------------------------------------------------------------------------
+const server = new McpServer({ name: pkg.name, version: pkg.version });
+
+server.registerTool(
+  'ask_meteora_docs',
+  {
+    title: 'Ask Meteora Docs',
+    description:
+      "Ask a natural-language question about Meteora's Solana protocols and get an answer " +
+      "from Meteora's OFFICIAL documentation AI assistant (docs.meteora.ag). " +
+      'Best for: Dynamic Bonding Curve (DBC), DAMM v1/v2, DLMM, dynamic fees & fee sharing, ' +
+      'Alpha Vault, fee scheduling, anti-sniper config, migration, and SDK usage. ' +
+      'Returns the assistant’s prose answer (plus the doc searches it ran).',
+    inputSchema: {
+      question: z
+        .string()
+        .min(3)
+        .describe('The question to ask, e.g. "How does the Dynamic Bonding Curve migration work?"'),
+      path: z
+        .string()
+        .optional()
+        .describe(
+          'Optional docs path to scope the assistant’s context, e.g. ' +
+            '"overview/products/dbc/what-is-dbc". Defaults to "overview".'
+        ),
+    },
+  },
+  async ({ question, path }) => {
+    try {
+      const { answer, searches, usage } = await askMeteora(question, path);
+      let text = answer || '(The assistant returned an empty answer.)';
+      if (searches && searches.length) {
+        text = '_Searched: ' + searches.join(' | ') + '_\n\n' + text;
+      }
+      if (usage && usage.usage) {
+        const u = usage.usage;
+        text += '\n\n_(tokens: ' + (u.promptTokens || '?') + '+' + (u.completionTokens || '?') + ')_';
+      }
+      return { content: [{ type: 'text', text }] };
+    } catch (e) {
+      return {
+        content: [{ type: 'text', text: 'Error asking Meteora docs: ' + (e && e.message ? e.message : String(e)) }],
+        isError: true,
+      };
+    }
+  }
+);
+
+// ---------------------------------------------------------------------------
+// Boot + graceful shutdown
+// ---------------------------------------------------------------------------
+let shuttingDown = false;
+function shutdown() {
+  if (shuttingDown) return;
+  shuttingDown = true;
+  const done = () => process.exit(0);
+  if (cycleTLSPromise) {
+    cycleTLSPromise.then((c) => { try { c.exit(); } catch {} }).then(done, done);
+    setTimeout(done, 2000).unref();
+  } else {
+    done();
+  }
+}
+process.on('SIGINT', shutdown);
+process.on('SIGTERM', shutdown);
+
+async function main() {
+  const transport = new StdioServerTransport();
+  await server.connect(transport);
+  process.stderr.write('[meteora-docs-mcp] v' + pkg.version + ' running on stdio\n');
+}
+
+main().catch((e) => {
+  process.stderr.write('[meteora-docs-mcp] fatal: ' + (e && e.message ? e.message : String(e)) + '\n');
+  process.exit(1);
+});

package/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "meteora-docs-mcp",
+  "version": "1.0.0",
+  "description": "MCP server that answers questions from Meteora's official documentation AI assistant (DBC, DAMM, DLMM, dynamic fees, and more).",
+  "type": "commonjs",
+  "main": "index.js",
+  "bin": {
+    "meteora-docs-mcp": "index.js"
+  },
+  "files": [
+    "index.js",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "start": "node index.js"
+  },
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "modelcontextprotocol",
+    "meteora",
+    "solana",
+    "dbc",
+    "dlmm",
+    "damm",
+    "defi",
+    "documentation",
+    "ai-assistant"
+  ],
+  "license": "MIT",
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.29.0",
+    "cycletls": "^2.0.5",
+    "zod": "^3.25.0"
+  }
+}