修复连接；在 smithery.yaml 中加入 configSchema

Author: AvatarGanymede

smithery.yaml

@@ -1 +1,12 @@
 runtime: typescript
+
+# Config schema for Smithery to show API Key form when users connect
+configSchema:
+  type: object
+  properties:
+    mineruApiKey:
+      type: string
+      title: MinerU API Key
+      description: Your MinerU API Key (obtain from https://mineru.net/apiManage/token)
+      x-from:
+        header: x-mineru-api-key

src/index.ts

@@ -113,11 +113,15 @@ export default function createServer(
   config: z.infer<typeof configSchema>
 ) {
   const apiToken = config.mineruApiKey || process.env.MINERU_API_KEY || "";
-  if (!apiToken) {
-    throw new Error(
-      "MinerU API Key is required. Provide it via configSchema or set MINERU_API_KEY environment variable."
-    );
-  }
+
+  const requireApiKey = () => {
+    if (!apiToken || apiToken === SANDBOX_PLACEHOLDER_KEY) {
+      throw new Error(
+        "MinerU API Key is required. Please configure your API key in Smithery/Cursor settings. " +
+          "Get your key from https://mineru.net/apiManage/token"
+      );
+    }
+  };
 
   const server = new McpServer({
     name: "mineru-markdown-converter",
@@ -208,6 +212,7 @@ export default function createServer(
         .describe("Enable table recognition"),
     },
     async ({ url, model_version, is_ocr, enable_formula, enable_table }) => {
+      requireApiKey();
       const ext = guessExtFromUrl(url);
       const params = autoConfigureParams(ext, model_version, is_ocr);
 
@@ -242,6 +247,7 @@ export default function createServer(
         .describe("Batch ID returned from create_parse_task (file upload)"),
     },
     async ({ task_id, batch_id }) => {
+      requireApiKey();
       if (!task_id && !batch_id) {
         return {
           content: [
@@ -294,6 +300,7 @@ export default function createServer(
     max_wait_seconds: number,
     poll_interval: number
   ) {
+    requireApiKey();
     const ext = guessExtFromUrl(url);
     const params = autoConfigureParams(ext, model_version);
 
@@ -450,10 +457,14 @@ export default function createServer(
   return server;
 }
 
+/** Placeholder key for sandbox mode — connection works, tools return friendly error */
+export const SANDBOX_PLACEHOLDER_KEY = "sandbox-placeholder-key";
+
 /**
- * Sandbox server for Smithery scanning.
- * Uses a dummy key so Smithery can discover tools without real credentials.
+ * Sandbox server for Smithery scanning and connection handshake.
+ * Uses a dummy key so Smithery can discover tools and connect without real credentials.
+ * Tool calls return a friendly error asking the user to configure their API key.
  */
 export function createSandboxServer() {
-  return createServer({ mineruApiKey: "sandbox-placeholder-key" });
+  return createServer({ mineruApiKey: SANDBOX_PLACEHOLDER_KEY });
 }

src/server-http.ts

@@ -9,7 +9,7 @@
 import { createServer as createHttpServer } from "node:http";
 import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
 import { zodToJsonSchema } from "zod-to-json-schema";
-import createServer, { configSchema } from "./index.js";
+import createServer, { configSchema, createSandboxServer } from "./index.js";
 import type { IncomingMessage, ServerResponse } from "node:http";
 
 const PORT = parseInt(process.env.PORT || "10000", 10);
@@ -216,7 +216,12 @@ async function handleRequest(req: IncomingMessage, res: ServerResponse) {
   if ((method === "GET" || method === "POST") && path === "/mcp") {
     const config = getConfig(req);
     try {
-      const server = createServer(config);
+      // Use sandbox server when no API key: allows Smithery connection handshake
+      // to succeed (initialize, tools/list). Tool calls will fail with friendly error.
+      const server =
+        config.mineruApiKey || process.env.MINERU_API_KEY
+          ? createServer(config)
+          : createSandboxServer();
       const transport = new StreamableHTTPServerTransport({
         sessionIdGenerator: undefined,
       });