zhihu-mcp-proxy 1.1.0

package/README.md

@@ -0,0 +1,74 @@
+# zhihu-mcp-proxy
+
+MCP server for Zhihu Search — bridges Zhihu's official [MCP-over-SSE API](https://developer.zhihu.com/) to stdio.
+
+## Quick Start
+
+```bash
+npx zhihu-mcp-proxy
+```
+
+Requires `ZHIHU_ACCESS_SECRET` environment variable.
+
+## Configuration
+
+### Claude Desktop / OpenClaw / any MCP client
+
+```json
+{
+  "mcpServers": {
+    "zhihu-search": {
+      "command": "npx",
+      "args": ["zhihu-mcp-proxy"],
+      "env": {
+        "ZHIHU_ACCESS_SECRET": "your_access_secret_here"
+      }
+    }
+  }
+}
+```
+
+### OpenClaw `openclaw.json`
+
+```json
+{
+  "mcp": {
+    "servers": {
+      "zhihu-search": {
+        "command": "npx",
+        "args": ["zhihu-mcp-proxy"],
+        "env": {
+          "ZHIHU_ACCESS_SECRET": "your_access_secret_here"
+        }
+      }
+    }
+  }
+}
+```
+
+## Tool
+
+### `zhihu_search`
+
+| Parameter | Type   | Required | Description                        |
+|-----------|--------|----------|------------------------------------|
+| `query`   | string | ✅       | Search keywords, 2-100 characters  |
+| `count`   | number | ❌       | Number of results (1-10, default 10) |
+
+Returns structured XML with titles, authors, content snippets, and ranking scores.
+
+## How It Works
+
+1. On startup, connects to Zhihu's SSE endpoint with your access_secret
+2. Receives the `endpoint` event with a session-specific message URL
+3. Initializes the MCP session over that channel
+4. Exposes `zhihu_search` as a local stdio MCP tool
+5. Forwards tool calls to Zhihu and returns results
+
+## Getting an Access Secret
+
+Apply at [Zhihu Open Platform](https://developer.zhihu.com/).
+
+## License
+
+MIT

package/bin.js

@@ -0,0 +1,208 @@
+#!/usr/bin/env node
+
+/**
+ * zhihu-mcp-proxy
+ *
+ * Zhihu Search MCP Proxy — bridges Zhihu's MCP-over-SSE endpoint
+ * to a local stdio MCP server that OpenClaw can consume.
+ *
+ * Environment variables:
+ *   ZHIHU_ACCESS_SECRET  (required) — Bearer token for Zhihu MCP API
+ */
+
+const { McpServer } = require("@modelcontextprotocol/sdk/server/mcp.js");
+const { StdioServerTransport } = require("@modelcontextprotocol/sdk/server/stdio.js");
+const { z } = require("zod");
+const { EventSource } = require("eventsource");
+
+const ZHIHU_SSE_URL = "https://developer.zhihu.com/api/mcp/zhihu_search/v1/sse";
+const ZHIHU_MSG_BASE = "https://developer.zhihu.com/api/mcp/zhihu_search/v1/message";
+const SSE_CONNECT_TIMEOUT = 15_000;
+
+// ── Zhihu SSE client ────────────────────────────────────────────────
+
+class ZhihuSSEClient {
+  constructor(accessSecret) {
+    this.accessSecret = accessSecret;
+    this.es = null;
+    this.messageUrl = null;
+    this.rpcId = 0;
+    this.pending = new Map();
+    this.initialized = false;
+  }
+
+  async connect() {
+    return new Promise((resolve, reject) => {
+      let settled = false;
+      const connectTimer = setTimeout(() => {
+        if (!settled) {
+          settled = true;
+          reject(new Error("SSE connection timeout — did not receive endpoint event within 15s"));
+        }
+      }, SSE_CONNECT_TIMEOUT);
+
+      const es = new EventSource(ZHIHU_SSE_URL, {
+        headers: {
+          Authorization: `Bearer ${this.accessSecret}`,
+        },
+      });
+
+      es.addEventListener("endpoint", (e) => {
+        const path = e.data;
+        if (path && !settled) {
+          clearTimeout(connectTimer);
+          settled = true;
+          this.messageUrl = new URL(path, ZHIHU_MSG_BASE).href;
+          this.es = es;
+          resolve();
+        }
+      });
+
+      es.addEventListener("message", (e) => {
+        try {
+          const msg = JSON.parse(e.data);
+          this._handleMessage(msg);
+        } catch {
+          // ignore non-JSON
+        }
+      });
+
+      es.addEventListener("error", () => {
+        if (!settled) {
+          clearTimeout(connectTimer);
+          settled = true;
+          reject(new Error("SSE connection failed — check ZHIHU_ACCESS_SECRET or network"));
+        }
+      });
+    });
+  }
+
+  async initialize() {
+    const result = await this._send("initialize", {
+      protocolVersion: "2024-11-05",
+      clientInfo: { name: "zhihu-mcp-proxy", version: "1.0.0" },
+      capabilities: {},
+    });
+    this.initialized = true;
+    return result;
+  }
+
+  async callTool(name, args) {
+    return this._send("tools/call", { name, arguments: args });
+  }
+
+  _send(method, params) {
+    return new Promise((resolve, reject) => {
+      const id = ++this.rpcId;
+      const timer = setTimeout(() => {
+        this.pending.delete(id);
+        reject(new Error(`RPC timeout for ${method} (id=${id})`));
+      }, 30_000);
+
+      this.pending.set(id, { resolve, reject, timer });
+
+      const body = JSON.stringify({
+        jsonrpc: "2.0",
+        id,
+        method,
+        params,
+      });
+
+      fetch(this.messageUrl, {
+        method: "POST",
+        headers: {
+          Authorization: `Bearer ${this.accessSecret}`,
+          "Content-Type": "application/json",
+        },
+        body,
+      }).catch((err) => {
+        clearTimeout(timer);
+        this.pending.delete(id);
+        reject(err);
+      });
+    });
+  }
+
+  _handleMessage(msg) {
+    const { id, result, error } = msg;
+    if (id == null) return;
+    const entry = this.pending.get(id);
+    if (!entry) return;
+    clearTimeout(entry.timer);
+    this.pending.delete(id);
+    if (error) {
+      entry.reject(new Error(error.message || JSON.stringify(error)));
+    } else {
+      entry.resolve(result);
+    }
+  }
+
+  close() {
+    if (this.es) {
+      this.es.close();
+      this.es = null;
+    }
+  }
+}
+
+// ── MCP Server ──────────────────────────────────────────────────────
+
+async function main() {
+  const accessSecret = process.env.ZHIHU_ACCESS_SECRET;
+  if (!accessSecret) {
+    console.error("Error: ZHIHU_ACCESS_SECRET environment variable is required");
+    process.exit(1);
+  }
+
+  const client = new ZhihuSSEClient(accessSecret);
+  await client.connect();
+  await client.initialize();
+
+  const server = new McpServer({
+    name: "zhihu-search",
+    version: "1.0.0",
+  });
+
+  server.tool(
+    "zhihu_search",
+    "Search Zhihu for articles, answers, and posts. Returns structured XML results with titles, authors, and content snippets.",
+    {
+      query: z.string().min(2).max(100).describe("Search keywords, 2-100 characters"),
+      count: z.number().min(1).max(10).optional().describe("Number of results to return (1-10, default 10)"),
+    },
+    async ({ query, count }) => {
+      try {
+        const result = await client.callTool("zhihu_search", {
+          query,
+          count: count ?? 10,
+        });
+        if (result?.content) {
+          return { content: result.content };
+        }
+        return {
+          content: [{ type: "text", text: JSON.stringify(result) }],
+        };
+      } catch (err) {
+        return {
+          content: [{ type: "text", text: `Error searching Zhihu: ${err.message}` }],
+          isError: true,
+        };
+      }
+    }
+  );
+
+  const transport = new StdioServerTransport();
+  await server.connect(transport);
+
+  const cleanup = () => {
+    client.close();
+    process.exit(0);
+  };
+  process.on("SIGINT", cleanup);
+  process.on("SIGTERM", cleanup);
+}
+
+main().catch((err) => {
+  console.error("Fatal:", err.message);
+  process.exit(1);
+});

package/package.json

@@ -0,0 +1,29 @@
+{
+  "name": "zhihu-mcp-proxy",
+  "version": "1.1.0",
+  "description": "MCP server for Zhihu Search — bridges Zhihu's official MCP-over-SSE API to stdio for npx usage",
+  "main": "bin.js",
+  "bin": {
+    "zhihu-mcp-proxy": "./bin.js"
+  },
+  "files": [
+    "bin.js",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "keywords": [
+    "mcp",
+    "mcp-server",
+    "zhihu",
+    "zhihu-search",
+    "search",
+    "model-context-protocol"
+  ],
+  "license": "MIT",
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.12.1",
+    "eventsource": "^3.0.6"
+  }
+}