ap-test-mcp-cli 0.0.1

package/README.md

@@ -0,0 +1,120 @@
+# mcp-cli
+
+MCP（Model Context Protocol）命令行客户端：管理 MCP 服务、列出/调用 tools、资源与 prompts。
+
+---
+
+## 安装与运行
+
+```bash
+pnpm install
+```
+
+**运行方式（任选其一）：**
+
+```bash
+pnpm start -- <子命令> [选项]
+# 或
+node bin/mcp-cli.js -- <子命令> [选项]
+```
+
+沙箱/CI 等无法 `npm install -g` 时，用上述方式在项目目录下执行即可。
+
+---
+
+## 全局选项
+
+| 选项 | 说明 |
+|------|------|
+| `-s, --server <name>` | 指定 MCP 服务器名，部分子命令必填 |
+| `--json` | 输出机器可读 JSON |
+| `-v, --version` | 显示版本 |
+
+---
+
+## 命令一览
+
+### server — 服务器列表与连通性
+
+| 子命令 | 说明 | 选项 | 状态 |
+|--------|------|------|------|
+| `server list` | 列出已配置的 MCP 服务器 | — | ✅ 高德（见 MCP_AMAP_*） |
+| `server check` | 检查指定/全部服务器连通性 | `-s`；`--all` | ✅ 高德 |
+
+---
+
+### tool — 工具列表、详情与调用
+
+| 子命令 | 说明 | 必填/选项 | 状态 |
+|--------|------|-----------|------|
+| `tool list` | 列出可用工具 | `-s`；`--save <file>`、`--allow-tools <csv>` | ✅ 高德 |
+| `tool get` | 查看单个工具详情 | `-s`、`--tool <name>`；`--allow-tools <csv>` | ✅ 高德 |
+| `tool call` | 执行工具 | `-s`、`--tool <name>`、`--input <json>` | ✅ 高德 |
+
+---
+
+### resource — 资源列表、详情与读取
+
+| 子命令 | 说明 | 必填/选项 | 状态 |
+|--------|------|-----------|------|
+| `resource list` | 列出资源 | `-s` | ⏳ 占位 |
+| `resource get` | 资源元信息 | `-s`、`--resource <path_or_id>` | ⏳ 占位 |
+| `resource read` | 读取资源内容 | `-s`、`--resource <path_or_id>`；`--format text\|json` | ⏳ 占位 |
+
+---
+
+### prompt — 提示词列表、详情与调用
+
+| 子命令 | 说明 | 必填/选项 | 状态 |
+|--------|------|-----------|------|
+| `prompt list` | 列出 prompts | `-s` | ⏳ 占位 |
+| `prompt get` | 单个 prompt 详情 | `-s`、`--prompt <name>` | ⏳ 占位 |
+| `prompt call` | 调用 prompt | `-s`、`--prompt <name>`；`--args <json>` | ⏳ 占位 |
+
+---
+
+### auth — OAuth 登录 / 登出 / 状态
+
+| 子命令 | 说明 | 选项 | 状态 |
+|--------|------|------|------|
+| `auth login` | 登录 OAuth 服务 | `-s`；`--force` | ⏳ 占位 |
+| `auth logout` | 清除本地令牌 | `-s` | ⏳ 占位 |
+| `auth status` | 查看登录状态 | `-s` | ⏳ 占位 |
+
+---
+
+### serve — 启动 MCP RPC 服务端
+
+| 说明 | 选项 | 状态 |
+|------|------|------|
+| 本地启动 MCP 服务（供客户端连接） | `--port <port>`（默认 8080）、`--config <path>` | ⏳ 占位 |
+
+---
+
+## 环境变量
+
+脚本会按顺序加载：`.env` → `.env.local` → `.env.local.test`，后加载覆盖前者。
+
+**高德 MCP（`-s amap`）：**
+
+- `MCP_AMAP_KEY` — 高德开放平台 Key（会拼成 `https://mcp.amap.com/mcp?key=...`）
+- 或 `MCP_AMAP_URL` — 完整 MCP 端点 URL（含 key 等）
+
+---
+
+## 高德 MCP 测试
+
+配置上述任一变量后：
+
+```bash
+pnpm run test:amap
+```
+
+会依次执行：`server list`、`server check -s amap`、`tool list -s amap`、`tool call -s amap --tool maps_weather --input '{"city":"北京"}'`。未配置则跳过并退出 0。
+
+---
+
+## 当前实现状态
+
+- **已实现：** `server list/check`、`tool list/get/call` 支持高德 MCP（`-s amap`），底层为 `shared/request.js` + `shared/mcp.js` + `shared/amap.js`。
+- **占位：** `resource`、`prompt`、`auth`、`serve` 仅有子命令骨架。

package/bin/mcp-cli.js

@@ -0,0 +1,7 @@
+#!/usr/bin/env node
+
+"use strict";
+
+const { run } = require("../src/cli");
+
+run(process.argv);

package/package.json

@@ -0,0 +1,18 @@
+{
+  "name": "ap-test-mcp-cli",
+  "version": "0.0.1",
+  "description": "MCP command line tool",
+  "bin": {
+    "mcp-cli": "bin/mcp-cli.js"
+  },
+  "type": "commonjs",
+  "scripts": {
+    "start": "bash ./scripts/run-cli.sh",
+    "test": "bash ./scripts/test.sh",
+    "test:amap": "bash ./scripts/test-amap.sh"
+  },
+  "dependencies": {
+    "commander": "^12.1.0"
+  },
+  "license": "MIT"
+}

package/scripts/load-env.sh

@@ -0,0 +1,20 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+ROOT_DIR="$(cd "$(dirname "$0")/.." && pwd)"
+
+load_file() {
+  local file="$1"
+  if [[ -f "$file" ]]; then
+    set -a
+    # shellcheck disable=SC1090
+    source "$file"
+    set +a
+  fi
+}
+
+load_env() {
+  load_file "$ROOT_DIR/.env"
+  load_file "$ROOT_DIR/.env.local"
+  load_file "$ROOT_DIR/.env.local.test"
+}

package/scripts/run-cli.sh

@@ -0,0 +1,34 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+ROOT_DIR="$(cd "$(dirname "$0")/.." && pwd)"
+# shellcheck disable=SC1090
+source "$ROOT_DIR/scripts/load-env.sh"
+load_env
+
+ARGS=("$@")
+
+if [[ "${#ARGS[@]}" -ge 3 ]]; then
+  COMMAND="${ARGS[0]}"
+  LAST_INDEX=$(( ${#ARGS[@]} - 1 ))
+  LAST_VALUE="${ARGS[$LAST_INDEX]}"
+
+  HAS_SERVER_FLAG=0
+  for token in "${ARGS[@]}"; do
+    if [[ "$token" == "-s" || "$token" == "--server" || "$token" == --server=* ]]; then
+      HAS_SERVER_FLAG=1
+      break
+    fi
+  done
+
+  if [[ $HAS_SERVER_FLAG -eq 0 && "$LAST_VALUE" != -* ]]; then
+    case "$COMMAND" in
+      server|tool|auth|prompt|resource)
+        unset 'ARGS[$LAST_INDEX]'
+        ARGS+=("-s" "$LAST_VALUE")
+        ;;
+    esac
+  fi
+fi
+
+exec node "$ROOT_DIR/bin/mcp-cli.js" "${ARGS[@]}"

package/scripts/test-amap.sh

@@ -0,0 +1,26 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+ROOT_DIR="$(cd "$(dirname "$0")/.." && pwd)"
+# shellcheck disable=SC1090
+source "$ROOT_DIR/scripts/load-env.sh"
+load_env
+
+if [[ -z "${MCP_AMAP_KEY:-}" && -z "${MCP_AMAP_URL:-}" ]]; then
+  echo "Skip Amap test: set MCP_AMAP_KEY or MCP_AMAP_URL in .env.local or .env.local.test"
+  exit 0
+fi
+
+echo "[1/4] server list"
+node "$ROOT_DIR/bin/mcp-cli.js" server list
+
+echo "[2/4] server check -s amap"
+node "$ROOT_DIR/bin/mcp-cli.js" server check -s amap
+
+echo "[3/4] tool list -s amap"
+node "$ROOT_DIR/bin/mcp-cli.js" tool list -s amap
+
+echo "[4/4] tool call -s amap maps_weather 北京"
+node "$ROOT_DIR/bin/mcp-cli.js" tool call -s amap --tool maps_weather --input '{"city":"北京"}'
+
+echo "Amap test passed"

package/scripts/test.sh

@@ -0,0 +1,12 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+ROOT_DIR="$(cd "$(dirname "$0")/.." && pwd)"
+
+echo "[1/2] server list"
+node "$ROOT_DIR/bin/mcp-cli.js" server list
+
+echo "[2/2] tool list (requires -s; no backend)"
+node "$ROOT_DIR/bin/mcp-cli.js" tool list -s example
+
+echo "Test passed"

package/src/cli.js

@@ -0,0 +1,37 @@
+"use strict";
+
+const { Command } = require("commander");
+const { registerServerCommand } = require("./commands/server");
+const { registerAuthCommand } = require("./commands/auth");
+const { registerToolCommand } = require("./commands/tool");
+const { registerPromptCommand } = require("./commands/prompt");
+const { registerResourceCommand } = require("./commands/resource");
+const { registerServeCommand } = require("./commands/serve");
+
+function run(argv) {
+  const program = new Command();
+
+  program
+    .name("mcp-cli")
+    .description(
+      "A comprehensive command-line interface for interacting with Model Context Protocol servers.\n" +
+        "This CLI provides a unified way to manage MCP servers, execute tools, read resources,\n" +
+        "call prompts, and handle OAuth authentication across multiple MCP server instances."
+    )
+    .option("-s, --server <string>", "specify the server name")
+    .option("--json", "output machine-readable JSON")
+    .version("0.1.0", "-v, --version", "version for mcp-cli")
+    .showHelpAfterError();
+  program.configureHelp({ showGlobalOptions: true });
+
+  registerServerCommand(program);
+  registerAuthCommand(program);
+  registerToolCommand(program);
+  registerPromptCommand(program);
+  registerResourceCommand(program);
+  registerServeCommand(program);
+
+  program.parse(argv);
+}
+
+module.exports = { run };

package/src/commands/auth.js

@@ -0,0 +1,40 @@
+"use strict";
+
+const { requireGlobalServer } = require("../shared/server");
+
+function registerAuthCommand(program) {
+  const auth = program
+    .command("auth")
+    .description(
+      "Handle OAuth 2.1 authentication for MCP servers including login, logout, and status checking."
+    );
+
+  auth
+    .command("login")
+    .description("Authenticate with an OAuth-enabled MCP server")
+    .option("--force", "force re-login")
+    .action((options, command) => {
+      const server = requireGlobalServer(command, "auth login");
+      console.log(`Auth login for "${server}" (force=${Boolean(options.force)})... [stub]`);
+      console.log("Visit https://example.com/oauth/authorize to authorize");
+    });
+
+  auth
+    .command("logout")
+    .description("Clear stored OAuth tokens")
+    .action((_, command) => {
+      const server = requireGlobalServer(command, "auth logout");
+      console.log(`Auth logout for "${server}"... [stub]`);
+    });
+
+  auth
+    .command("status")
+    .description("Show authentication status")
+    .action((_, command) => {
+      const server = requireGlobalServer(command, "auth status");
+      console.log(`Auth status for "${server}"... [stub]`);
+      console.log("Authenticated, expires in 2h");
+    });
+}
+
+module.exports = { registerAuthCommand };

package/src/commands/prompt.js

@@ -0,0 +1,50 @@
+"use strict";
+
+const { requireGlobalServer } = require("../shared/server");
+
+function parseJsonFlag(raw, flagName) {
+  try {
+    return JSON.parse(raw);
+  } catch (err) {
+    console.error(`Invalid JSON for --${flagName}: ${err.message}`);
+    process.exit(1);
+  }
+}
+
+function registerPromptCommand(program) {
+  const prompt = program
+    .command("prompt")
+    .description("List, inspect, and call prompts on MCP servers with optional arguments.");
+
+  prompt
+    .command("list")
+    .description("List available prompts")
+    .action((_, command) => {
+      const server = requireGlobalServer(command, "prompt list");
+      console.log(`Prompts for "${server}"... [stub]`);
+      console.log("summarize-thread, draft-reply");
+    });
+
+  prompt
+    .command("get")
+    .description("Get detailed information about a specific prompt")
+    .requiredOption("--prompt <prompt_name>", "prompt name")
+    .action((options, command) => {
+      const server = requireGlobalServer(command, "prompt get");
+      console.log(`Prompt details for "${options.prompt}" on "${server}"... [stub]`);
+    });
+
+  prompt
+    .command("call")
+    .description("Call a prompt on an MCP server")
+    .requiredOption("--prompt <prompt_name>", "prompt name")
+    .option("--args <json>", "prompt args JSON")
+    .action((options, command) => {
+      const server = requireGlobalServer(command, "prompt call");
+      const parsedArgs = options.args ? parseJsonFlag(options.args, "args") : {};
+      console.log(`Calling prompt "${options.prompt}" on "${server}"... [stub]`);
+      console.log(JSON.stringify(parsedArgs, null, 2));
+    });
+}
+
+module.exports = { registerPromptCommand };

package/src/commands/resource.js

@@ -0,0 +1,43 @@
+"use strict";
+
+const { requireGlobalServer } = require("../shared/server");
+
+function registerResourceCommand(program) {
+  const resource = program
+    .command("resource")
+    .description("List, read, and inspect resources available on MCP servers.");
+
+  resource
+    .command("list")
+    .description("List available resources")
+    .action((_, command) => {
+      const server = requireGlobalServer(command, "resource list");
+      console.log(`Resources for "${server}"... [stub]`);
+      console.log("file:///notes/report.md");
+    });
+
+  resource
+    .command("get")
+    .description("Get detailed information about a specific resource")
+    .requiredOption("--resource <path_or_id>", "resource path or id")
+    .action((options, command) => {
+      const server = requireGlobalServer(command, "resource get");
+      console.log(`Resource metadata for "${options.resource}" on "${server}"... [stub]`);
+    });
+
+  resource
+    .command("read")
+    .description("Read a resource from an MCP server")
+    .requiredOption("--resource <path_or_id>", "resource path or id")
+    .option("--format <format>", "output format: text|json", "text")
+    .action((options, command) => {
+      const server = requireGlobalServer(command, "resource read");
+      if (!["text", "json"].includes(options.format)) {
+        console.error('[resource read] --format must be "text" or "json"');
+        process.exit(1);
+      }
+      console.log(`Reading resource "${options.resource}" on "${server}" as ${options.format}... [stub]`);
+    });
+}
+
+module.exports = { registerResourceCommand };

package/src/commands/serve.js

@@ -0,0 +1,25 @@
+"use strict";
+
+const { InvalidArgumentError } = require("commander");
+
+function parsePort(portRaw) {
+  const port = Number(portRaw);
+  if (!Number.isInteger(port) || port <= 0) {
+    throw new InvalidArgumentError("port must be a positive integer");
+  }
+  return port;
+}
+
+function registerServeCommand(program) {
+  program
+    .command("serve")
+    .description("Start the MCP RPC server")
+    .option("--port <port>", "listen port", parsePort, 8080)
+    .option("--config <path>", "config file path")
+    .action((options) => {
+      const config = options.config ? ` with config "${options.config}"` : "";
+      console.log(`Serving MCP at localhost:${options.port}${config} [stub]`);
+    });
+}
+
+module.exports = { registerServeCommand };

package/src/commands/server.js

@@ -0,0 +1,62 @@
+"use strict";
+
+const { CliError, ok, wrapAction } = require("../shared/output");
+const { postMcp } = require("../shared/mcp");
+const { AMAP_SERVER, getAmapTransport, getAmapUrl } = require("../shared/amap");
+
+function registerServerCommand(program) {
+  const server = program
+    .command("server")
+    .description("List enabled MCP servers and check their connectivity and capabilities.");
+
+  server
+    .command("list")
+    .description("List available MCP servers")
+    .action(wrapAction("server.list", async (_, command) => {
+      const servers = [];
+      if (getAmapUrl()) {
+        servers.push({ name: AMAP_SERVER, status: "configured" });
+      }
+      const message = servers.length ? `Available: ${servers.map((s) => s.name).join(", ")}` : "No servers configured";
+      ok(command, "server.list", message, { servers });
+    }));
+
+  server
+    .command("check")
+    .description("Check connectivity to MCP servers")
+    .option("--all", "check all servers")
+    .action(wrapAction("server.check", async (options, command) => {
+      const serverName = command.optsWithGlobals().server;
+      if (options.all || !serverName) {
+        const results = [];
+        if (getAmapUrl()) {
+          const transport = getAmapTransport();
+          try {
+            await postMcp(transport, "initialize", { protocolVersion: "2024-11-05", capabilities: {}, clientInfo: { name: "mcp-cli", version: "0.1.0" } });
+            const listRes = await postMcp(transport, "tools/list", {});
+            const count = listRes?.result?.tools?.length ?? 0;
+            results.push({ server: AMAP_SERVER, connected: true, tools: count });
+          } catch (err) {
+            results.push({ server: AMAP_SERVER, connected: false, error: err.message });
+          }
+        }
+        const message = results.length ? results.map((r) => `${r.server}: ${r.connected ? `connected, ${r.tools} tools` : r.error}`).join("; ") : "No servers configured";
+        ok(command, "server.check", message, { servers: results });
+        return;
+      }
+      if (serverName === AMAP_SERVER) {
+        const transport = getAmapTransport();
+        if (!transport) {
+          throw new CliError("[server check] Amap not configured. Set MCP_AMAP_KEY or MCP_AMAP_URL.", "ERR_AMAP_NOT_CONFIGURED");
+        }
+        await postMcp(transport, "initialize", { protocolVersion: "2024-11-05", capabilities: {}, clientInfo: { name: "mcp-cli", version: "0.1.0" } });
+        const listRes = await postMcp(transport, "tools/list", {});
+        const count = listRes?.result?.tools?.length ?? 0;
+        ok(command, "server.check", `Server "${AMAP_SERVER}": connected, ${count} tools`, { server: AMAP_SERVER, connected: true, tools: count });
+        return;
+      }
+      ok(command, "server.check", `Server "${serverName}": no backend configured`, { server: serverName, connected: false });
+    }));
+}
+
+module.exports = { registerServerCommand };

package/src/commands/tool.js

@@ -0,0 +1,105 @@
+"use strict";
+
+const fs = require("node:fs");
+const { CliError, ok, wrapAction } = require("../shared/output");
+const { postMcp } = require("../shared/mcp");
+const { AMAP_SERVER, getAmapTransport } = require("../shared/amap");
+
+function getRequiredServer(command, context) {
+  const server = command.optsWithGlobals().server;
+  if (!server) {
+    throw new CliError(`[${context}] Missing required global flag: -s or --server`, "ERR_MISSING_SERVER");
+  }
+  return server;
+}
+
+function parseJsonFlag(raw, flagName) {
+  try {
+    return JSON.parse(raw);
+  } catch (err) {
+    throw new CliError(`Invalid JSON for --${flagName}: ${err.message}`, "ERR_INVALID_JSON");
+  }
+}
+
+async function amapToolsList(transport, options) {
+  await postMcp(transport, "initialize", { protocolVersion: "2024-11-05", capabilities: {}, clientInfo: { name: "mcp-cli", version: "0.1.0" } });
+  const response = await postMcp(transport, "tools/list", {});
+  const tools = response?.result?.tools ?? [];
+  if (options?.save) {
+    fs.writeFileSync(options.save, JSON.stringify(response, null, 2), "utf8");
+  }
+  return { tools, response };
+}
+
+function registerToolCommand(program) {
+  const tool = program
+    .command("tool")
+    .description("List, inspect, and execute tools on MCP servers with JSON input support.");
+
+  tool
+    .command("list")
+    .description("List available tools")
+    .option("--save <file>", "save output path")
+    .option("--allow-tools <csv>", "comma-separated allowed tools")
+    .action(wrapAction("tool.list", async (options, command) => {
+      const server = getRequiredServer(command, "tool list");
+      if (server === AMAP_SERVER) {
+        const transport = getAmapTransport();
+        if (!transport) throw new CliError("[tool list] Amap not configured. Set MCP_AMAP_KEY or MCP_AMAP_URL.", "ERR_AMAP_NOT_CONFIGURED");
+        const { tools, response } = await amapToolsList(transport, options);
+        ok(command, "tool.list", `Tools for server "${server}"`, {
+          server,
+          count: tools.length,
+          tools,
+          savedTo: options.save || null
+        });
+        return;
+      }
+      ok(command, "tool.list", `Tools for server "${server}" (no backend configured)`, {
+        server,
+        count: 0,
+        tools: [],
+        savedTo: options.save || null
+      });
+    }));
+
+  tool
+    .command("get")
+    .description("Get detailed information about a specific tool")
+    .requiredOption("--tool <tool_name>", "tool name")
+    .option("--allow-tools <csv>", "comma-separated allowed tools")
+    .action(wrapAction("tool.get", async (options, command) => {
+      const server = getRequiredServer(command, "tool get");
+      if (server === AMAP_SERVER) {
+        const transport = getAmapTransport();
+        if (!transport) throw new CliError("[tool get] Amap not configured. Set MCP_AMAP_KEY or MCP_AMAP_URL.", "ERR_AMAP_NOT_CONFIGURED");
+        const { tools } = await amapToolsList(transport, {});
+        const found = tools.find((t) => t.name === options.tool);
+        if (!found) throw new CliError(`Tool "${options.tool}" not found.`, "ERR_TOOL_NOT_FOUND");
+        ok(command, "tool.get", `Tool "${options.tool}"`, found);
+        return;
+      }
+      throw new CliError(`[tool get] No backend configured for server "${server}".`, "ERR_NO_BACKEND");
+    }));
+
+  tool
+    .command("call")
+    .description("Execute a tool on an MCP server")
+    .requiredOption("--tool <tool_name>", "tool name")
+    .requiredOption("--input <json>", "tool input JSON")
+    .action(wrapAction("tool.call", async (options, command) => {
+      const server = getRequiredServer(command, "tool call");
+      if (server === AMAP_SERVER) {
+        const transport = getAmapTransport();
+        if (!transport) throw new CliError("[tool call] Amap not configured. Set MCP_AMAP_KEY or MCP_AMAP_URL.", "ERR_AMAP_NOT_CONFIGURED");
+        const payload = parseJsonFlag(options.input, "input");
+        await postMcp(transport, "initialize", { protocolVersion: "2024-11-05", capabilities: {}, clientInfo: { name: "mcp-cli", version: "0.1.0" } });
+        const response = await postMcp(transport, "tools/call", { name: options.tool, arguments: payload });
+        ok(command, "tool.call", `Called tool "${options.tool}"`, response?.result ?? response);
+        return;
+      }
+      throw new CliError(`[tool call] No backend configured for server "${server}".`, "ERR_NO_BACKEND");
+    }));
+}
+
+module.exports = { registerToolCommand };

package/src/shared/amap.js

@@ -0,0 +1,22 @@
+"use strict";
+
+const { createTransport } = require("./mcp");
+
+const AMAP_SERVER = "amap";
+const AMAP_MCP_BASE = "https://mcp.amap.com/mcp";
+
+function getAmapUrl() {
+  const url = process.env.MCP_AMAP_URL;
+  if (url) return url;
+  const key = process.env.MCP_AMAP_KEY;
+  if (key) return `${AMAP_MCP_BASE}?key=${key}`;
+  return null;
+}
+
+function getAmapTransport() {
+  const url = getAmapUrl();
+  if (!url) return null;
+  return createTransport(url);
+}
+
+module.exports = { AMAP_SERVER, getAmapUrl, getAmapTransport };

package/src/shared/mcp.js

@@ -0,0 +1,57 @@
+"use strict";
+
+const { randomUUID } = require("node:crypto");
+const { request } = require("./request");
+
+/**
+ * 通用 MCP 协议层：用给定的 transport 发一条 JSON-RPC，解析并返回整包；出错抛 Error。
+ * 不绑定任何具体 server（飞书/高德等），只关心「拼 JSON-RPC、调 transport、解析结果」。
+ *
+ * @param {(body: object) => Promise<string>} transport - 接收 JSON-RPC 对象，返回响应文本
+ * @param {string} method - MCP 方法名，如 "initialize" | "tools/list" | "tools/call"
+ * @param {object | null} [params] - 方法参数
+ * @returns {Promise<object>} 整包 JSON-RPC 响应（含 result / error）
+ */
+async function postMcp(transport, method, params) {
+  const body = {
+    jsonrpc: "2.0",
+    id: randomUUID(),
+    method,
+    params: params === undefined ? null : params
+  };
+
+  const text = await transport(body);
+  let parsed = null;
+  try {
+    parsed = text ? JSON.parse(text) : null;
+  } catch {
+    parsed = { raw: text };
+  }
+
+  if (parsed && parsed.error) {
+    const err = parsed.error;
+    const message = err.message || JSON.stringify(err);
+    throw new Error(`MCP error (${method}): ${message}`);
+  }
+
+  return parsed;
+}
+
+/**
+ * 根据 URL 和固定 headers 生成一个 transport 函数，供 postMcp 使用。
+ * 适用于鉴权在 query 或 header 里、且每次请求 headers 固定的场景（如高德 key 在 query）。
+ *
+ * @param {string} url - 完整 MCP 端点 URL
+ * @param {Record<string, string>} [headers={}] - 每次请求都带上的 headers（如 Accept、MCP-Protocol-Version）
+ * @returns {(body: object) => Promise<string>}
+ */
+function createTransport(url, headers = {}) {
+  const baseHeaders = {
+    "Accept": "application/json, text/event-stream",
+    "MCP-Protocol-Version": "2024-11-05",
+    ...headers
+  };
+  return (body) => request(url, { headers: baseHeaders, body: JSON.stringify(body) });
+}
+
+module.exports = { postMcp, createTransport, request };

package/src/shared/output.js

@@ -0,0 +1,91 @@
+"use strict";
+
+class CliError extends Error {
+  constructor(message, code = "ERR_CLI", details = null) {
+    super(message);
+    this.name = "CliError";
+    this.code = code;
+    this.details = details;
+  }
+}
+
+function isJsonMode(command) {
+  try {
+    return Boolean(command && command.optsWithGlobals && command.optsWithGlobals().json);
+  } catch {
+    return false;
+  }
+}
+
+function writeLine(stream, text) {
+  stream.write(`${text}\n`);
+}
+
+function emitResult(command, result) {
+  const jsonMode = isJsonMode(command);
+  const target = result.ok ? process.stdout : process.stderr;
+
+  if (jsonMode) {
+    writeLine(target, JSON.stringify(result, null, 2));
+    return;
+  }
+
+  if (result.ok) {
+    if (result.message) {
+      writeLine(process.stdout, result.message);
+    }
+    if (result.data !== undefined) {
+      writeLine(process.stdout, JSON.stringify(result.data, null, 2));
+    }
+    return;
+  }
+
+  writeLine(process.stderr, `[${result.error.code}] ${result.error.message}`);
+  if (result.error.details) {
+    writeLine(process.stderr, JSON.stringify(result.error.details, null, 2));
+  }
+}
+
+function ok(command, action, message, data) {
+  emitResult(command, {
+    ok: true,
+    action,
+    message,
+    data
+  });
+}
+
+function fail(command, action, error) {
+  const normalized =
+    error instanceof CliError
+      ? error
+      : new CliError(error && error.message ? error.message : String(error), "ERR_RUNTIME");
+
+  emitResult(command, {
+    ok: false,
+    action,
+    error: {
+      code: normalized.code || "ERR_RUNTIME",
+      message: normalized.message,
+      details: normalized.details || null
+    }
+  });
+  process.exit(1);
+}
+
+function wrapAction(action, handler) {
+  return async (options, command) => {
+    try {
+      await handler(options, command);
+    } catch (error) {
+      fail(command, action, error);
+    }
+  };
+}
+
+module.exports = {
+  CliError,
+  ok,
+  fail,
+  wrapAction
+};

package/src/shared/request.js

@@ -0,0 +1,35 @@
+"use strict";
+
+/**
+ * 底层 HTTP：对指定 URL 发 POST，带 headers 和 body，返回响应文本。
+ * 不关心 MCP、不关心具体业务，只负责「发请求、拿响应」。
+ * @param {string} url - 完整 URL（可含 query，如 ?key=xxx）
+ * @param {{ headers?: Record<string, string>; body: string }} options
+ * @returns {Promise<string>} 响应体文本
+ */
+async function request(url, { headers = {}, body }) {
+  const response = await fetch(url, {
+    method: "POST",
+    headers: {
+      "Content-Type": "application/json",
+      ...headers
+    },
+    body
+  });
+
+  const text = await response.text();
+  if (!response.ok) {
+    let message = `HTTP ${response.status}`;
+    try {
+      const json = JSON.parse(text);
+      if (json.error && json.error.message) message = json.error.message;
+      else if (json.msg) message = json.msg;
+    } catch {
+      // keep default message
+    }
+    throw new Error(message);
+  }
+  return text;
+}
+
+module.exports = { request };

package/src/shared/server.js

@@ -0,0 +1,12 @@
+"use strict";
+
+function requireGlobalServer(command, context) {
+  const server = command.optsWithGlobals().server;
+  if (!server) {
+    console.error(`[${context}] Missing required global flag: -s or --server`);
+    process.exit(1);
+  }
+  return server;
+}
+
+module.exports = { requireGlobalServer };