omnipost-mcp 0.0.0-stage → 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 OmniGoAI
+
+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

@@ -1,3 +1,72 @@
-# Temporary Holding Version
+# omnipost-mcp
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+MCP server for [OmniPost](https://omnigoai.com/en/products/omnipost/). It lets Claude Code, Claude Desktop, Cursor, Cline and other MCP clients publish articles, image posts and videos to 40+ platforms: Zhihu, CSDN, WeChat Official Accounts, Xiaohongshu, Bilibili, Weibo, Douyin, Dev.to, Mastodon, Bluesky, WordPress and more.
+
+This package does no publishing itself. It forwards your AI client's requests to the OmniPost desktop app running on the same machine, where your platform accounts are logged in. Nothing goes through a cloud server.
+
+[中文说明](#中文说明)
+
+## Requirements
+
+1. Install the OmniPost desktop app (Windows / macOS) from https://omnigoai.com/en/download/omnipost/ and keep it open.
+2. Log in to the platforms you want to publish to inside the app.
+3. Node.js 18.17 or newer.
+
+## Setup
+
+Claude Code:
+
+```bash
+claude mcp add omnipost -- npx -y omnipost-mcp
+```
+
+Claude Desktop, Cursor, Cline and other clients (MCP config file):
+
+```json
+{
+  "mcpServers": {
+    "omnipost": { "command": "npx", "args": ["-y", "omnipost-mcp"] }
+  }
+}
+```
+
+Then ask your agent something like: "Publish this Markdown to Zhihu and CSDN, and put it in my WeChat Official Account drafts."
+
+## How it works
+
+- Finds the running app through `~/.omnipost/server.json` (falls back to port 8787) and connects to its built-in MCP endpoint `http://127.0.0.1:<port>/sse`.
+- Tool list and tool calls are forwarded unchanged, so you always get the tools of the app version you have installed.
+- If the app is not running, the tools are still listed from a bundled snapshot, and each call returns a short "install / open OmniPost" message instead of a raw connection error.
+- Long calls (for example a large video upload) are allowed to run for up to 6 hours without being cut off.
+- Plan limits are enforced by the app, not by this package.
+
+Environment variables:
+
+- `OMNIPOST_MCP_URL`: use a specific endpoint, e.g. `http://127.0.0.1:8787/sse`.
+- `OMNIPOST_DATA_DIR`: where to look for `server.json` (default `~/.omnipost`).
+
+You can also connect to the app directly without this package if your client supports SSE: `claude mcp add --transport sse omnipost http://127.0.0.1:8787/sse`.
+
+## Development
+
+```bash
+npm install
+npm test           # bridge tests against a fake app
+npm run snapshot   # refresh tools-snapshot.json from the app running on this machine
+```
+
+## 中文说明
+
+`omnipost-mcp` 让 Claude Code、Claude Desktop、Cursor 等 AI 工具通过标准 MCP 协议调用 OmniPost，把写好的内容发到知乎、CSDN、公众号、小红书、B 站等 40 多个平台。
+
+它本身不发布，只把请求转给你电脑上正在运行的 OmniPost 桌面应用，账号登录都在应用里，不经过任何云端。
+
+1. 安装并打开 OmniPost：https://omnigoai.com/zh/download/omnipost/ ，在应用里登录要发的平台。
+2. Claude Code 里运行：`claude mcp add omnipost -- npx -y omnipost-mcp`。其它客户端按上面的配置文件写法添加。
+3. 对 AI 说「把这篇发到知乎和 CSDN，公众号进草稿箱」。
+
+应用没开时，AI 工具仍能看到工具列表，调用时会提示先安装并打开 OmniPost。
+
+## License
+
+MIT

package/package.json

@@ -1,6 +1,53 @@
 {
   "name": "omnipost-mcp",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.1",
+  "description": "MCP server for OmniPost: lets Claude Code, Claude Desktop, Cursor and other MCP clients publish articles, image posts and videos to 40+ Chinese and overseas platforms through the OmniPost desktop app running on your machine.",
+  "mcpName": "io.github.OmniGoAI/omnipost",
+  "type": "module",
+  "bin": {
+    "omnipost-mcp": "src/index.js"
+  },
+  "main": "src/index.js",
+  "files": [
+    "src/",
+    "tools-snapshot.json",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "start": "node src/index.js",
+    "test": "node --test \"test/*.test.js\"",
+    "snapshot": "node scripts/snapshot.mjs"
+  },
+  "engines": {
+    "node": ">=18.17"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.29.0",
+    "undici": "^6.21.0"
+  },
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "omnipost",
+    "claude",
+    "publishing",
+    "xiaohongshu",
+    "wechat",
+    "zhihu",
+    "csdn",
+    "bilibili",
+    "multi-platform"
+  ],
+  "homepage": "https://github.com/OmniGoAI/omnipost-skill/tree/main/mcp",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/OmniGoAI/omnipost-skill.git",
+    "directory": "mcp"
+  },
+  "bugs": {
+    "url": "https://github.com/OmniGoAI/omnipost-skill/issues"
+  },
+  "license": "MIT",
+  "author": "OmniGoAI"
+}

package/src/bridge.js

@@ -0,0 +1,190 @@
+// OmniPost MCP bridge.
+//
+// A standard MCP server that does no work itself: it forwards tool listing and tool calls to the
+// OmniPost desktop app running on the same machine (its built-in MCP endpoint, http://127.0.0.1:<port>/sse).
+// When the app is not running, tools are still listed from a bundled snapshot so clients and
+// directories can introspect the server, and every call returns a clear "install / open OmniPost" hint.
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import { Client } from '@modelcontextprotocol/sdk/client/index.js';
+import { SSEClientTransport } from '@modelcontextprotocol/sdk/client/sse.js';
+import { CallToolRequestSchema, ListToolsRequestSchema } from '@modelcontextprotocol/sdk/types.js';
+import { Agent, fetch as undiciFetch } from 'undici';
+
+export const DEFAULT_PORT = 8787;
+export const DOWNLOAD_URL = 'https://omnigoai.com/en/download/omnipost/';
+
+// Publishing a large video can keep a tool call open for a long time. Keep this in line with the
+// OmniPost CLI (6 hours). A client-side timeout here would make the agent think the publish failed
+// and retry it, uploading the same content twice.
+export const CALL_TIMEOUT_MS = 6 * 3600 * 1000;
+
+// Number of tool calls currently in progress. The process waits for these before exiting, so a
+// client that closes stdin right after sending a request still gets its answer.
+let inFlightCalls = 0;
+export const inFlight = () => inFlightCalls;
+
+// Node's built-in fetch drops a response body that stays idle for 5 minutes. The app's SSE stream
+// is silent while a long publish is running, so use a dispatcher without body/header timeouts.
+const longLivedAgent = new Agent({ bodyTimeout: 0, headersTimeout: 0, keepAliveTimeout: 60_000 });
+const longLivedFetch = (url, init = {}) => undiciFetch(url, { ...init, dispatcher: longLivedAgent });
+
+/** Where the running app's MCP endpoint is. Order: OMNIPOST_MCP_URL > ~/.omnipost/server.json > default port. */
+export function resolveEndpoint({ env = process.env, home = os.homedir() } = {}) {
+  if (env.OMNIPOST_MCP_URL) return env.OMNIPOST_MCP_URL;
+  const dataDir = env.OMNIPOST_DATA_DIR || path.join(home, '.omnipost');
+  let port = DEFAULT_PORT;
+  try {
+    const info = JSON.parse(fs.readFileSync(path.join(dataDir, 'server.json'), 'utf8'));
+    if (Number.isInteger(info?.port) && info.port > 0) port = info.port;
+  } catch {
+    // no server.json yet: fall back to the default port
+  }
+  return `http://127.0.0.1:${port}/sse`;
+}
+
+export function loadSnapshot(file = new URL('../tools-snapshot.json', import.meta.url)) {
+  try {
+    const data = JSON.parse(fs.readFileSync(file, 'utf8'));
+    return Array.isArray(data?.tools) ? data.tools : [];
+  } catch {
+    return [];
+  }
+}
+
+export function notRunningResult(endpoint, cause) {
+  const text = [
+    'OmniPost desktop app is not reachable, so this tool could not run.',
+    `Tried: ${endpoint}${cause ? ` (${cause})` : ''}`,
+    '',
+    'To fix: install OmniPost and keep it open, then log in to the platforms you want to publish to inside the app.',
+    `Download: ${DOWNLOAD_URL}`,
+    '',
+    '未检测到正在运行的 OmniPost 桌面应用，工具无法执行。请先安装并打开 OmniPost，在应用里登录要发布的平台账号后重试。',
+  ].join('\n');
+  return { content: [{ type: 'text', text }], isError: true };
+}
+
+/**
+ * Connection to the desktop app, created lazily and recreated after a failure, so the bridge picks
+ * the app up whenever the user opens or restarts it.
+ */
+export class AppConnection {
+  constructor({ resolve = () => resolveEndpoint(), connectTimeoutMs = 5000, transportFactory } = {}) {
+    this.resolve = resolve;
+    this.connectTimeoutMs = connectTimeoutMs;
+    this.transportFactory = transportFactory || ((url) => new SSEClientTransport(new URL(url), {
+      fetch: longLivedFetch,
+      eventSourceInit: { fetch: longLivedFetch },
+    }));
+    this.client = null;
+    this.endpoint = null;
+  }
+
+  async get() {
+    if (this.client) return this.client;
+    const endpoint = this.resolve();
+    const client = new Client({ name: 'omnipost-mcp-bridge', version: '0.1.1' });
+    client.onclose = () => { if (this.client === client) this.client = null; };
+    const connecting = client.connect(this.transportFactory(endpoint));
+    let timer;
+    const timeout = new Promise((_, reject) => {
+      timer = setTimeout(() => reject(new Error(`connect timed out after ${this.connectTimeoutMs} ms`)), this.connectTimeoutMs);
+    });
+    try {
+      await Promise.race([connecting, timeout]);
+    } catch (err) {
+      try { await client.close(); } catch { /* ignore */ }
+      throw Object.assign(err instanceof Error ? err : new Error(String(err)), { endpoint });
+    } finally {
+      clearTimeout(timer);
+    }
+    this.client = client;
+    this.endpoint = endpoint;
+    return client;
+  }
+
+  async reset() {
+    const c = this.client;
+    this.client = null;
+    if (c) { try { await c.close(); } catch { /* ignore */ } }
+  }
+}
+
+function shortCause(err) {
+  return String(err?.cause?.code || err?.code || err?.message || err).slice(0, 160);
+}
+
+export function createBridgeServer({ connection = new AppConnection(), snapshot = loadSnapshot(), version = '0.1.1' } = {}) {
+  const server = new Server(
+    { name: 'omnipost', version },
+    {
+      capabilities: { tools: {} },
+      instructions:
+        'OmniPost publishes content you have already written to 40+ platforms (Zhihu, CSDN, WeChat Official Accounts, ' +
+        'Xiaohongshu, Bilibili, Dev.to, Mastodon, Bluesky, WordPress...). It needs the OmniPost desktop app running on ' +
+        'this machine with the target accounts logged in. Call list_alerts before publishing; most Chinese platforms ' +
+        'create drafts by default.',
+    },
+  );
+
+  server.setRequestHandler(ListToolsRequestSchema, async () => {
+    try {
+      const client = await connection.get();
+      return await client.listTools();
+    } catch {
+      await connection.reset();
+      return { tools: snapshot };
+    }
+  });
+
+  server.setRequestHandler(CallToolRequestSchema, async (request) => {
+    inFlightCalls += 1;
+    try {
+      return await handleCall(request);
+    } finally {
+      inFlightCalls -= 1;
+    }
+  });
+
+  async function handleCall(request) {
+    const { name, arguments: args } = request.params;
+    let client;
+    try {
+      client = await connection.get();
+    } catch (err) {
+      await connection.reset();
+      return notRunningResult(err?.endpoint || connection.resolve(), shortCause(err));
+    }
+    try {
+      return await client.callTool({ name, arguments: args || {} }, undefined, {
+        timeout: CALL_TIMEOUT_MS,
+        maxTotalTimeout: CALL_TIMEOUT_MS,
+      });
+    } catch (err) {
+      // The link dropped mid-call (app closed or restarted). Do not retry automatically: the call may
+      // already have published something, and a blind retry could publish it twice.
+      await connection.reset();
+      return {
+        content: [{
+          type: 'text',
+          text: `Lost the connection to the OmniPost app during "${name}" (${shortCause(err)}). ` +
+            'It may or may not have completed. Check list_posts before retrying so nothing is published twice.',
+        }],
+        isError: true,
+      };
+    }
+  }
+
+  // When the AI client goes away, drop the link to the app too, so nothing is left open.
+  server.onclose = () => { if (inFlightCalls === 0) connection.reset(); };
+
+  return server;
+}
+
+/** Close pooled sockets so the process can exit promptly (used on shutdown and in tests). */
+export async function shutdown() {
+  try { await longLivedAgent.close(); } catch { /* ignore */ }
+}

package/src/index.js

@@ -0,0 +1,37 @@
+#!/usr/bin/env node
+// omnipost-mcp: stdio MCP server that forwards to the OmniPost desktop app on this machine.
+//   Claude Code:   claude mcp add omnipost -- npx -y omnipost-mcp
+//   Other clients: { "command": "npx", "args": ["-y", "omnipost-mcp"] }
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { createBridgeServer, resolveEndpoint, shutdown, inFlight } from './bridge.js';
+
+let exiting = false;
+async function exit(code = 0, { immediate = false } = {}) {
+  if (exiting) return;
+  exiting = true;
+  // Let calls that are already running finish and send their answers first. The short pause lets a
+  // request that arrived just before stdin closed get registered as in flight.
+  if (!immediate) await new Promise((r) => setTimeout(r, 300));
+  while (!immediate && inFlight() > 0) await new Promise((r) => setTimeout(r, 200));
+  await shutdown();
+  process.exit(code);
+}
+
+async function main() {
+  const server = createBridgeServer();
+  const transport = new StdioServerTransport();
+  const prev = server.onclose;
+  server.onclose = () => { prev?.(); exit(0); };
+  await server.connect(transport);
+  // The client closing our stdin means it is done with us.
+  process.stdin.on('end', () => exit(0));
+  process.stdin.on('close', () => exit(0));
+  process.on('SIGINT', () => exit(0, { immediate: true }));
+  process.on('SIGTERM', () => exit(0, { immediate: true }));
+  process.stderr.write(`[omnipost-mcp] ready, forwarding to ${resolveEndpoint()}\n`);
+}
+
+main().catch((err) => {
+  process.stderr.write(`[omnipost-mcp] failed to start: ${err?.stack || err}\n`);
+  exit(1, { immediate: true });
+});