doc2mcp 0.1.16 → 0.1.18

package/README.md

@@ -1,6 +1,6 @@
 <div align="center">
 
-<img src="./assets/doc2mcp-cli-banner.png" alt="doc2mcp — turn any docs site into a hosted MCP server from your terminal" width="100%" />
+<img src="https://doc2mcp.site/doc2mcp-cli-banner.png" alt="doc2mcp — turn any docs site into a hosted MCP server from your terminal" width="100%" />
 
 # doc2mcp
 
@@ -13,7 +13,7 @@ Point it at a docs URL, and doc2mcp crawls, analyzes, and serves it as a token-s
 [![node](https://img.shields.io/node/v/doc2mcp?color=8b5cf6&logo=node.js)](https://nodejs.org)
 [![license](https://img.shields.io/npm/l/doc2mcp?color=8b5cf6)](https://github.com/gautammanak1/doc2mcp/blob/main/LICENSE)
 
-[Website](https://doc2mcp.site) · [Playground](https://doc2mcp.site/playground) · [Docs](https://doc2mcp.site/docs) · [CLI guide](https://doc2mcp.site/docs/cli)
+[Website](https://doc2mcp.site) · [CLI](https://doc2mcp.site/cli) · [Docs](https://doc2mcp.site/docs) · [CLI guide](https://doc2mcp.site/docs/cli)
 
 </div>
 
@@ -29,6 +29,20 @@ npm install -g doc2mcp
 > Install with **`-g`** (global). The `doc2mcp` command only lands on your `PATH` when installed globally.
 > If you ran `npm i doc2mcp` (without `-g`) and see `command not found: doc2mcp`, either reinstall with `-g`
 > or run it through your package runner: `npx doc2mcp <docs-url>`.
+>
+> If `npm install -g doc2mcp` succeeds but `doc2mcp` is still `command not found`, your npm global bin folder is
+> not on PATH. Run:
+>
+> ```bash
+> echo 'export PATH="'$(npm prefix -g)'/bin:$PATH"' >> ~/.zshrc
+> source ~/.zshrc
+> ```
+>
+> Quick no-setup option:
+>
+> ```bash
+> npx doc2mcp login
+> ```
 
 Other package managers:
 
@@ -51,11 +65,16 @@ doc2mcp https://docs.stripe.com
 
 # 3. When it's ready, pick your editor — the MCP is installed for you
 #    ✔ Cursor   ✔ VS Code   ✔ Claude Desktop   ✔ Windsurf
+
+# 4. Chat with your docs without leaving the terminal
+doc2mcp chat
+
+# Or paste a docs URL directly into chat mode
+doc2mcp chat https://uagents.fetch.ai/docs
 ```
 
-That's it. The same hosted pipeline powers the [website](https://doc2mcp.site) and the
-[Playground](https://doc2mcp.site/playground), so a project you create in the CLI shows up in your
-dashboard and marketplace too.
+That's it. The same hosted pipeline powers the [website](https://doc2mcp.site), so a project you
+create in the CLI shows up in your dashboard and marketplace too.
 
 ## Commands
 
@@ -67,6 +86,7 @@ dashboard and marketplace too.
 | [`doc2mcp whoami`](#doc2mcp-whoami) | Show the account you're signed in as |
 | [`doc2mcp list`](#doc2mcp-list) | List the MCP projects on your account |
 | [`doc2mcp install <projectId>`](#doc2mcp-install-projectid) | Install an existing MCP into your editors |
+| [`doc2mcp chat [target]`](#doc2mcp-chat-target) | Chat with your docs in the terminal; target can be a project ID or docs URL |
 | `doc2mcp --version` | Print the installed CLI version |
 | `doc2mcp --help` | Show usage and all commands |
 
@@ -92,7 +112,7 @@ Tips:
 - Point at the **docs** URL (`https://docs.stripe.com`), not the marketing homepage.
 - The URL must start with `http://` or `https://`.
 - Conversions count against your plan's monthly limit (free includes 5/month), shared with the
-  website, Playground, and chat.
+  website and chat.
 
 ---
 
@@ -161,6 +181,32 @@ You'll be prompted to choose which detected clients to write to:
 
 Existing config is merged, not overwritten.
 
+---
+
+### `doc2mcp chat [target]`
+
+Chat with your docs **right from the terminal**. doc2mcp answers natural-language questions from
+the crawled documentation — with cited sources — using the project's hosted MCP (the same
+`ask_documentation` tool your editor calls). This is the Playground experience, in a Claude Code-style shell loop.
+
+```bash
+# Interactive: paste a docs URL, project ID, or choose an existing MCP
+doc2mcp chat
+
+# Paste a docs URL directly: doc2mcp converts it, then starts chat
+doc2mcp chat https://uagents.fetch.ai/docs
+
+# Skip the picker by passing a project ID
+doc2mcp chat prj_123abc
+
+# One-shot answer (handy in scripts / CI)
+doc2mcp chat prj_123abc -m "How do I authenticate requests?"
+```
+
+- With no arguments, you pick from your `ready` projects.
+- Type `/exit` to leave an interactive session.
+- Each answer lists the source pages it used so you can verify it.
+
 ## Configuration
 
 | Setting | Default | Notes |
@@ -172,10 +218,11 @@ Existing config is merged, not overwritten.
 
 | Symptom | Fix |
 | --- | --- |
-| `command not found: doc2mcp` | You installed locally or your shell cached PATH. Reinstall with `npm i -g doc2mcp`, then run `hash -r` or open a new terminal. You can also use `npx doc2mcp <url>`. |
+| `command not found: doc2mcp` | You installed locally or npm's global bin is not on PATH. Use `npx doc2mcp <url>`, or add `$(npm prefix -g)/bin` to PATH in `~/.zshrc`. |
+| `pnpm add -g doc2mcp` says `ERR_PNPM_NO_GLOBAL_BIN_DIR` | Run `pnpm setup`, then `source ~/.zshrc`, then retry `pnpm add -g doc2mcp`. |
 | Browser doesn't open on `login` | Copy the printed URL into your browser manually, then approve. |
 | `login` can't reach the server | Confirm you're online; for self-hosting set `DOC2MCP_API_URL` to your instance. |
-| "Limit reached" | You've hit your plan's monthly conversion limit (shared across CLI, web, and Playground). |
+| "Limit reached" | You've hit your plan's monthly conversion limit (shared across CLI and web). |
 | Editor doesn't pick up the MCP | Fully restart the editor after install so it reloads MCP config. |
 
 ## How it works
@@ -209,7 +256,7 @@ already exists).
 
 - 📦 npm: https://www.npmjs.com/package/doc2mcp
 - 🌐 Website: https://doc2mcp.site
-- 🕹️ Playground: https://doc2mcp.site/playground
+- 🖥️ CLI page: https://doc2mcp.site/cli
 - 📚 Docs: https://doc2mcp.site/docs
 - 🧭 CLI guide: https://doc2mcp.site/docs/cli
 

package/dist/index.js

@@ -2,7 +2,7 @@
 
 // src/index.ts
 import { Command } from "commander";
-import pc6 from "picocolors";
+import pc7 from "picocolors";
 
 // src/commands/account.ts
 import pc from "picocolors";
@@ -73,8 +73,11 @@ async function runWhoami() {
 `);
 }
 
-// src/commands/convert.ts
-import pc5 from "picocolors";
+// src/commands/chat.ts
+import { createInterface } from "readline/promises";
+import { stdin as input, stdout as output } from "process";
+import ora2 from "ora";
+import pc6 from "picocolors";
 
 // src/api.ts
 import pc2 from "picocolors";
@@ -136,6 +139,9 @@ function printError(error) {
 `);
 }
 
+// src/commands/convert.ts
+import pc5 from "picocolors";
+
 // src/commands/login.ts
 import open from "open";
 import ora from "ora";
@@ -454,63 +460,69 @@ function printStatus(detail) {
     `\r${pc5.cyan("Status:")} ${project.status.padEnd(12)} ${pc5.dim(project.name)}`
   );
 }
-async function runConvert(sourceUrl) {
-  try {
-    await ensureLoggedIn();
-    process.stdout.write(`${pc5.bold("Converting")} ${sourceUrl}
+async function convertUrlToProject(sourceUrl, options = { offerInstall: true }) {
+  await ensureLoggedIn();
+  process.stdout.write(`${pc5.bold("Converting")} ${sourceUrl}
 `);
-    const created = await apiFetch("/api/cli/convert", {
-      method: "POST",
-      body: JSON.stringify({ sourceUrl })
-    });
-    process.stdout.write(`${pc5.dim("Project:")} ${created.id}
+  const created = await apiFetch("/api/cli/convert", {
+    method: "POST",
+    body: JSON.stringify({ sourceUrl })
+  });
+  process.stdout.write(`${pc5.dim("Project:")} ${created.id}
 `);
-    let delayMs = 2e3;
-    const terminal = /* @__PURE__ */ new Set(["ready", "error"]);
-    while (true) {
-      const detail = await apiFetch(
-        `/api/cli/projects/${created.id}`
-      );
-      printStatus(detail);
-      if (terminal.has(detail.project.status)) {
-        process.stdout.write("\n");
-        break;
-      }
-      await sleep2(delayMs);
-      delayMs = Math.min(delayMs + 1e3, 1e4);
-    }
-    const finalDetail = await apiFetch(
+  let delayMs = 2e3;
+  const terminal = /* @__PURE__ */ new Set(["ready", "error"]);
+  while (true) {
+    const detail = await apiFetch(
       `/api/cli/projects/${created.id}`
     );
-    if (finalDetail.project.status === "error") {
-      const lastLog = finalDetail.project.logs.at(-1);
-      process.stderr.write(
-        `${pc5.red("Conversion failed.")}${lastLog ? ` ${lastLog.message}` : ""}
-`
-      );
-      process.exitCode = 1;
-      return;
+    printStatus(detail);
+    if (terminal.has(detail.project.status)) {
+      process.stdout.write("\n");
+      break;
     }
-    if (!finalDetail.mcp || !finalDetail.install) {
-      process.stderr.write(`${pc5.red("MCP ready but missing install bundle.")}
+    await sleep2(delayMs);
+    delayMs = Math.min(delayMs + 1e3, 1e4);
+  }
+  const finalDetail = await apiFetch(
+    `/api/cli/projects/${created.id}`
+  );
+  if (finalDetail.project.status === "error") {
+    const lastLog = finalDetail.project.logs.at(-1);
+    process.stderr.write(
+      `${pc5.red("Conversion failed.")}${lastLog ? ` ${lastLog.message}` : ""}
+`
+    );
+    process.exitCode = 1;
+    return null;
+  }
+  if (!finalDetail.mcp || !finalDetail.install) {
+    process.stderr.write(`${pc5.red("MCP ready but missing install bundle.")}
 `);
-      process.exitCode = 1;
-      return;
-    }
-    process.stdout.write(`
+    process.exitCode = 1;
+    return null;
+  }
+  process.stdout.write(`
 ${pc5.green("MCP ready")}
 `);
-    process.stdout.write(`${pc5.bold("Server:")} ${finalDetail.mcp.serverName}
+  process.stdout.write(`${pc5.bold("Server:")} ${finalDetail.mcp.serverName}
 `);
-    process.stdout.write(`${pc5.bold("URL:")} ${finalDetail.mcp.url}
+  process.stdout.write(`${pc5.bold("URL:")} ${finalDetail.mcp.url}
 `);
-    process.stdout.write(`${pc5.bold("Token:")} ${finalDetail.mcp.token}
+  process.stdout.write(`${pc5.bold("Token:")} ${finalDetail.mcp.token}
 `);
-    process.stdout.write(
-      `${pc5.dim("Also listed in the doc2mcp marketplace when ready.")}
+  process.stdout.write(
+    `${pc5.dim("Also listed in the doc2mcp marketplace when ready.")}
 `
-    );
+  );
+  if (options.offerInstall) {
     await promptInstall(finalDetail.install);
+  }
+  return finalDetail;
+}
+async function runConvert(sourceUrl) {
+  try {
+    await convertUrlToProject(sourceUrl, { offerInstall: true });
   } catch (error) {
     printError(error);
     process.exitCode = 1;
@@ -539,9 +551,216 @@ async function runList() {
   }
 }
 
+// src/commands/chat.ts
+function isDocsUrl(value) {
+  try {
+    const url = new URL(value);
+    return url.protocol === "http:" || url.protocol === "https:";
+  } catch {
+    return false;
+  }
+}
+function createPrompt() {
+  return createInterface({ input, output });
+}
+async function readLine(prompt) {
+  const rl = createPrompt();
+  try {
+    const answer = await rl.question(prompt);
+    return answer.trim();
+  } catch {
+    return null;
+  } finally {
+    rl.close();
+  }
+}
+async function listReadyProjects() {
+  const data = await apiFetch(
+    "/api/cli/projects"
+  );
+  return data.projects.filter((p) => p.status === "ready");
+}
+async function pickExistingProject() {
+  const ready = await listReadyProjects();
+  if (ready.length === 0) {
+    process.stdout.write(
+      `${pc6.yellow("No ready MCP projects yet.")} Paste a docs URL to create one.
+`
+    );
+    return null;
+  }
+  process.stdout.write(`${pc6.dim("Ready MCPs")}
+`);
+  ready.forEach((p, index) => {
+    process.stdout.write(
+      `  ${pc6.cyan(String(index + 1).padStart(2, " "))}. ${pc6.bold(p.name)} ${pc6.dim(p.sourceUrl ?? p.id)}
+`
+    );
+  });
+  const choice = await readLine(
+    `${pc6.bold(">")} choose number, paste URL, or paste project id: `
+  );
+  if (!choice) {
+    return null;
+  }
+  if (isDocsUrl(choice)) {
+    return await convertUrlToProject(choice, { offerInstall: false });
+  }
+  const chosenIndex = Number(choice);
+  if (Number.isInteger(chosenIndex) && chosenIndex > 0) {
+    const project = ready.at(chosenIndex - 1);
+    if (project) {
+      return await apiFetch(`/api/cli/projects/${project.id}`);
+    }
+  }
+  return await apiFetch(`/api/cli/projects/${choice}`);
+}
+async function resolveProject(target) {
+  if (target) {
+    if (isDocsUrl(target)) {
+      return await convertUrlToProject(target, { offerInstall: false });
+    }
+    return await apiFetch(`/api/cli/projects/${target}`);
+  }
+  process.stdout.write(`${pc6.bold("doc2mcp chat")}
+`);
+  process.stdout.write(
+    `${pc6.dim("Paste a docs URL to create a new MCP, paste a project id, or press Enter to choose existing.")}
+
+`
+  );
+  const first = await readLine(`${pc6.bold(">")} docs url or project id: `);
+  if (!first) {
+    return await pickExistingProject();
+  }
+  if (isDocsUrl(first)) {
+    return await convertUrlToProject(first, { offerInstall: false });
+  }
+  return await apiFetch(`/api/cli/projects/${first}`);
+}
+async function askDocs(mcp, question) {
+  const response = await fetch(mcp.url, {
+    method: "POST",
+    headers: {
+      "Content-Type": "application/json",
+      Authorization: `Bearer ${mcp.token}`
+    },
+    body: JSON.stringify({
+      jsonrpc: "2.0",
+      id: 1,
+      method: "tools/call",
+      params: { name: "ask_documentation", arguments: { question } }
+    })
+  });
+  const payload = await response.json();
+  if (!response.ok || payload.error) {
+    throw new ApiError(
+      payload.error?.message ?? `MCP request failed (${response.status})`,
+      response.status,
+      payload
+    );
+  }
+  const raw = payload.result?.content?.[0]?.text ?? "";
+  try {
+    return JSON.parse(raw);
+  } catch {
+    return { question, answer: raw };
+  }
+}
+function renderAnswer(answer) {
+  process.stdout.write(`
+${pc6.cyan("\u256D\u2500 doc2mcp")}
+`);
+  for (const line of answer.answer.trim().split("\n")) {
+    process.stdout.write(`${pc6.cyan("\u2502")} ${line}
+`);
+  }
+  if (answer.sources && answer.sources.length > 0) {
+    process.stdout.write(`${pc6.cyan("\u2502")}
+${pc6.cyan("\u2502")} ${pc6.dim("Sources:")}
+`);
+    for (const source of answer.sources.slice(0, 6)) {
+      process.stdout.write(
+        `${pc6.cyan("\u2502")} ${pc6.dim("\u2022")} ${source.title} ${pc6.dim(source.url)}
+`
+      );
+    }
+  }
+  process.stdout.write(`${pc6.cyan("\u2570")}
+
+`);
+}
+async function answerOnce(mcp, question) {
+  const spinner = ora2("Thinking\u2026").start();
+  try {
+    const answer = await askDocs(mcp, question);
+    spinner.stop();
+    renderAnswer(answer);
+  } catch (error) {
+    spinner.fail("Failed to get an answer");
+    printError(error);
+  }
+}
+async function runChat(target, options = {}) {
+  try {
+    await ensureLoggedIn();
+    const detail = await resolveProject(target);
+    if (!detail) {
+      return;
+    }
+    if (!detail.mcp) {
+      process.stderr.write(
+        `${pc6.red("That project is not ready yet.")} Check: ${pc6.bold("doc2mcp list")}
+`
+      );
+      process.exitCode = 1;
+      return;
+    }
+    const { mcp } = detail;
+    if (options.message) {
+      await answerOnce(mcp, options.message);
+      return;
+    }
+    process.stdout.write(
+      `
+${pc6.cyan("\u256D\u2500")} ${pc6.bold(`Chatting with ${detail.project.name}`)}
+`
+    );
+    process.stdout.write(
+      `${pc6.cyan("\u2502")} ${pc6.dim("Ask anything about these docs. Type /exit to leave.")}
+`
+    );
+    process.stdout.write(`${pc6.cyan("\u2570")}
+
+`);
+    let active = true;
+    while (active) {
+      const question = await readLine(`${pc6.bold(">")} `);
+      if (question === null) {
+        active = false;
+        break;
+      }
+      const trimmed = question.trim();
+      if (!trimmed) {
+        continue;
+      }
+      if (trimmed === "/exit" || trimmed === "/quit") {
+        active = false;
+        break;
+      }
+      await answerOnce(mcp, trimmed);
+    }
+    process.stdout.write(`${pc6.dim("Bye \u2014 your docs MCP stays live for your editor.")}
+`);
+  } catch (error) {
+    printError(error);
+    process.exitCode = 1;
+  }
+}
+
 // src/index.ts
 var program = new Command();
-program.name("doc2mcp").description("Generate documentation MCP servers from your terminal").version("0.1.16", "-v, --version", "Print the installed CLI version");
+program.name("doc2mcp").description("Generate documentation MCP servers from your terminal").version("0.1.18", "-v, --version", "Print the installed CLI version");
 program.command("login").description("Authorize the CLI via browser").action(async () => {
   await runLogin();
 });
@@ -557,6 +776,9 @@ program.command("list").description("List your MCP projects").action(async () =>
 program.command("install <projectId>").description("Install an existing MCP into Cursor, VS Code, Claude, or Windsurf").action(async (projectId) => {
   await runInstallCommand(projectId);
 });
+program.command("chat [target]").description("Chat with docs in the terminal; target can be a project id or docs URL").option("-m, --message <text>", "Ask a single question and exit").action(async (target, options) => {
+  await runChat(target, options);
+});
 program.argument("[url]", "Documentation URL to convert").action(async (url) => {
   if (!url) {
     program.help();
@@ -569,7 +791,7 @@ program.argument("[url]", "Documentation URL to convert").action(async (url) =>
     }
   } catch {
     process.stderr.write(
-      `${pc6.red("Error:")} Invalid URL. Example: doc2mcp https://docs.example.com
+      `${pc7.red("Error:")} Invalid URL. Example: doc2mcp https://docs.example.com
 `
     );
     process.exitCode = 1;
@@ -579,7 +801,7 @@ program.argument("[url]", "Documentation URL to convert").action(async (url) =>
 });
 program.parseAsync(process.argv).catch((error) => {
   const message = error instanceof Error ? error.message : "Unknown error";
-  process.stderr.write(`${pc6.red("Error:")} ${message}
+  process.stderr.write(`${pc7.red("Error:")} ${message}
 `);
   process.exit(1);
 });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "doc2mcp",
-  "version": "0.1.16",
+  "version": "0.1.18",
   "description": "Turn any documentation site into a hosted MCP server from your terminal — for Cursor, Claude, VS Code, Windsurf, and OpenAI agents.",
   "type": "module",
   "bin": {
@@ -18,6 +18,7 @@
   "files": [
     "assets",
     "dist",
+    "scripts",
     "README.md"
   ],
   "engines": {
@@ -26,6 +27,7 @@
   "scripts": {
     "build": "tsup",
     "dev": "tsup --watch",
+    "postinstall": "node ./scripts/postinstall.js",
     "prepublishOnly": "pnpm build"
   },
   "keywords": [

package/scripts/postinstall.js

@@ -0,0 +1,48 @@
+#!/usr/bin/env node
+
+import { execFileSync } from "node:child_process";
+import path from "node:path";
+
+function isGlobalInstall() {
+  return (
+    process.env.npm_config_global === "true" ||
+    process.env.npm_config_location === "global"
+  );
+}
+
+function npmGlobalBin() {
+  try {
+    const prefix = execFileSync("npm", ["prefix", "-g"], {
+      encoding: "utf8",
+      stdio: ["ignore", "pipe", "ignore"],
+    }).trim();
+    return path.join(prefix, "bin");
+  } catch {
+    return "";
+  }
+}
+
+if (isGlobalInstall()) {
+  const binDir = npmGlobalBin();
+  const pathEntries = (process.env.PATH || "").split(path.delimiter);
+  if (binDir && !pathEntries.includes(binDir)) {
+    process.stdout.write(`
+doc2mcp installed, but npm's global bin is not on your PATH.
+
+Run this once for zsh:
+  echo 'export PATH="${binDir}:$PATH"' >> ~/.zshrc
+  source ~/.zshrc
+
+Then try:
+  doc2mcp login
+
+Quick alternative (no PATH setup):
+  npx doc2mcp login
+
+For pnpm global installs, run:
+  pnpm setup
+  source ~/.zshrc
+
+`);
+  }
+}