ym-hermes-desktop 1.0.0

package/README.md

@@ -0,0 +1,118 @@
+# ym-hermes-desktop
+
+本地 Hermes 接入点客户端（Node.js）。通过配置接入 **Hermes Agent 的 API server**（OpenAI 兼容接口），让你的 AI 工具/脚本调用 Hermes——Hermes 会自行执行它注册的工具（包括 MCP 工具）并返回结果。纯本地运行，零额外依赖（Node 22 内置 fetch）。
+
+## 环境要求
+
+- Node.js **20+**
+- **Hermes Agent 已安装并启动 API server**（本机已配置好，端口 8642）
+
+## 安装
+
+```bash
+cd ~/Desktop/ym-hermes-desktop
+npm install
+```
+
+## 配置
+
+编辑 `.env`（已配好，密钥为本机 Hermes API server 的 Bearer token）：
+
+```
+HERMES_API_ENDPOINT=http://127.0.0.1:8642/v1
+HERMES_API_KEY=你的 Bearer token
+HERMES_MODEL=hermes-agent
+```
+
+- `HERMES_API_ENDPOINT`：Hermes API server 地址（默认本地 8642）
+- `HERMES_API_KEY`：Hermes 的 `API_SERVER_KEY`（与 `~/.hermes/.env` 一致）
+- `HERMES_MODEL`：`/v1/models` 返回的模型 id（默认 `hermes-agent`）
+
+## 使用
+
+```bash
+npm run check      # 检查 Hermes 接入点是否可用
+npm run models     # 查看模型列表
+npm start          # 交互模式：直接输入问题，Hermes 执行并回答
+npm run ask "帮我查一下今天杭州天气"   # 单次提问
+```
+
+交互模式内可用 `/models`、`/check`、`/help`、`/exit`。
+
+## 作为模块接入你自己的 AI 工具
+
+`src/hermes.js` 可直接 import：
+
+```js
+import { chat, listModels } from './src/hermes.js';
+
+// 简单对话
+const r = await chat({ messages: [{ role: 'user', content: '你好' }] });
+console.log(r.choices[0].message.content);
+
+// 透传 tools（function calling）给 Hermes 编排
+const r2 = await chat({
+  messages: [{ role: 'user', content: '搜索 AI 相关的文章' }],
+  tools: [...],          // 可选：传给 Hermes 的工具定义
+});
+```
+
+Hermes 内部已注册的 MCP 工具会自动通过 function calling 被调用，无需在本地重复接入。
+
+## 发布到 npm 后（作为包安装使用）
+
+```bash
+npm i -g ym-hermes-desktop        # 全局安装
+# 配置环境变量（包内不读取 .env，用系统环境变量）
+export HERMES_API_ENDPOINT=http://127.0.0.1:8642/v1
+export HERMES_API_KEY=你的 Bearer token
+export HERMES_MODEL=hermes-agent
+ym-hermes                          # 启动交互 CLI
+```
+
+或作为库：
+
+```js
+import { chat } from 'ym-hermes-desktop';
+const r = await chat({ messages: [{ role: 'user', content: '你好' }] });
+```
+
+> 说明：`ym-hermes-desktop` 的发布包只包含 `src/` 与 `README.md`，不含任何本地配置文件与密钥。
+
+## 作为 MCP server 使用（发布到 npm 的形态）
+
+包内置 stdio MCP server，任何 MCP 客户端（Cursor / Claude Desktop / Cherry Studio 等）可连接：
+
+```json
+{
+  "mcpServers": {
+    "ym-hermes": {
+      "command": "npx",
+      "args": ["-y", "ym-hermes-desktop", "ym-hermes-mcp"],
+      "env": {
+        "HERMES_API_ENDPOINT": "http://127.0.0.1:8642/v1",
+        "HERMES_API_KEY": "你的 Bearer token",
+        "HERMES_MODEL": "hermes-agent"
+      }
+    }
+  }
+}
+```
+
+本地调试：
+
+```bash
+npm run mcp        # 以 MCP server 方式启动（stdio）
+```
+
+暴露的工具：
+
+| 工具 | 参数 | 说明 |
+| --- | --- | --- |
+| `hermes_chat` | `question`（或 `messages`） | 让 Hermes 处理任务，Hermes 自动调度其注册的工具/MCP |
+
+## 常见问题
+
+- **`✗ Hermes 接入点不可用`**：Hermes API server 未启动。检查 `hermes gateway status`，若 api_server 被拒绝，确认 `~/.hermes/.env` 中 `API_SERVER_KEY` 是强密钥（≥32 字符，可用 `openssl rand -hex 32` 生成），然后 `hermes gateway restart`。
+- **HTTP 401**：`.env` 的 `HERMES_API_KEY` 与 Hermes 实际 `API_SERVER_KEY` 不一致。
+- **想接入更多 MCP 工具**：在 Hermes 里注册即可（`hermes mcp add` 或配置 `~/.hermes/config.yaml` 的 mcp_servers），无需改本工具。

package/package.json

@@ -0,0 +1,44 @@
+{
+  "name": "ym-hermes-desktop",
+  "version": "1.0.0",
+  "description": "Hermes Agent 接入点客户端与 MCP server：把 Hermes（含其 MCP 工具）通过 OpenAI 兼容 API / MCP stdio 协议暴露给任意 AI 工具。",
+  "type": "module",
+  "main": "./src/hermes.js",
+  "exports": {
+    ".": "./src/hermes.js",
+    "./hermes": "./src/hermes.js",
+    "./config": "./src/config.js",
+    "./server": "./src/mcp-server.js"
+  },
+  "bin": {
+    "ym-hermes": "src/index.js",
+    "ym-hermes-mcp": "src/mcp-server.js"
+  },
+  "files": [
+    "src",
+    "README.md"
+  ],
+  "scripts": {
+    "start": "node src/index.js",
+    "ask": "node src/index.js --ask",
+    "models": "node src/index.js --models",
+    "check": "node src/index.js --check",
+    "mcp": "node src/mcp-server.js"
+  },
+  "keywords": [
+    "hermes",
+    "mcp",
+    "model-context-protocol",
+    "api-server",
+    "openai-compatible",
+    "agent",
+    "cli"
+  ],
+  "license": "MIT",
+  "engines": {
+    "node": ">=20"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.12.0"
+  }
+}

package/src/config.js

@@ -0,0 +1,44 @@
+/**
+ * config.js — 配置加载
+ * 读取项目根目录 .env（HERMES_API_* 系列）
+ */
+import { readFileSync, existsSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import path from 'node:path';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+export const ROOT_DIR = path.resolve(__dirname, '..');
+const ENV_PATH = path.join(ROOT_DIR, '.env');
+
+/** 简单解析 .env（支持 # 注释、引号、空行） */
+export function loadDotEnv(filePath = ENV_PATH) {
+  const result = {};
+  if (!existsSync(filePath)) return result;
+  const lines = readFileSync(filePath, 'utf-8').split(/\r?\n/);
+  for (const raw of lines) {
+    const line = raw.trim();
+    if (!line || line.startsWith('#')) continue;
+    const eq = line.indexOf('=');
+    if (eq === -1) continue;
+    const key = line.slice(0, eq).trim();
+    let value = line.slice(eq + 1).trim();
+    if (
+      (value.startsWith('"') && value.endsWith('"')) ||
+      (value.startsWith("'") && value.endsWith("'"))
+    ) {
+      value = value.slice(1, -1);
+    }
+    if (key) result[key] = value;
+  }
+  return result;
+}
+
+/** 读取 Hermes 接入点配置（环境变量优先，.env 仅本地开发兜底） */
+export function loadEnv() {
+  const dot = loadDotEnv();
+  return {
+    endpoint: (process.env.HERMES_API_ENDPOINT || dot.HERMES_API_ENDPOINT || '').replace(/\/+$/, ''),
+    apiKey: process.env.HERMES_API_KEY || dot.HERMES_API_KEY || '',
+    model: process.env.HERMES_MODEL || dot.HERMES_MODEL || 'hermes-agent',
+  };
+}

package/src/hermes.js

@@ -0,0 +1,61 @@
+/**
+ * hermes.js — Hermes Agent API 客户端
+ * 通过 OpenAI 兼容接口（Hermes API server）发起对话，
+ * Hermes 会自行执行它已注册的工具（含 MCP 工具），把结果返回。
+ * 支持 tools 参数透传（function calling），方便你自己的 AI 工具编排。
+ */
+import { loadEnv } from './config.js';
+
+const { endpoint, apiKey, model } = loadEnv();
+
+/** 发起一次 chat 请求（非流式） */
+export async function chat({ messages, tools = [], toolChoice = undefined, temperature = undefined }) {
+  if (!endpoint || !apiKey) {
+    throw new Error('未配置 Hermes 接入点：请检查 .env 中的 HERMES_API_ENDPOINT / HERMES_API_KEY');
+  }
+  const body = { model, messages };
+  if (tools && tools.length) body.tools = tools;
+  if (toolChoice) body.tool_choice = toolChoice;
+  if (temperature !== undefined) body.temperature = temperature;
+
+  const resp = await fetch(`${endpoint}/chat/completions`, {
+    method: 'POST',
+    headers: {
+      'Content-Type': 'application/json',
+      Authorization: `Bearer ${apiKey}`,
+    },
+    body: JSON.stringify(body),
+  });
+
+  if (!resp.ok) {
+    const text = await resp.text();
+    throw new Error(`Hermes API 请求失败 (HTTP ${resp.status}): ${text.slice(0, 500)}`);
+  }
+  return resp.json();
+}
+
+/** 查询模型列表 */
+export async function listModels() {
+  const resp = await fetch(`${endpoint}/models`, {
+    headers: { Authorization: `Bearer ${apiKey}` },
+  });
+  if (!resp.ok) throw new Error(`Hermes API 请求失败 (HTTP ${resp.status})`);
+  const data = await resp.json();
+  return (data.data || []).map((m) => m.id);
+}
+
+/** 输出 chat 响应中可读的部分（含工具调用过程） */
+export function summarizeChoice(choice) {
+  const msg = choice.message || {};
+  const lines = [];
+  if (Array.isArray(msg.tool_calls)) {
+    for (const tc of msg.tool_calls) {
+      if (tc.function) {
+        lines.push(`[调用工具] ${tc.function.name}(${tc.function.arguments})`);
+      }
+    }
+  }
+  if (msg.content) lines.push(String(msg.content));
+  if (lines.length === 0) lines.push('(无文本输出)');
+  return lines.join('\n');
+}

package/src/index.js

@@ -0,0 +1,117 @@
+#!/usr/bin/env node
+/**
+ * index.js — ym-hermes-desktop 入口（Hermes 接入点客户端）
+ *
+ * 用法：
+ *   npm start                 进入交互模式（输入问题，Hermes 执行并回答）
+ *   npm run ask "你的问题"     单次提问
+ *   npm run models            查看 Hermes API 模型列表
+ *   npm run check             检查 Hermes 接入点是否可用
+ *
+ * Hermes 会自行执行它注册的工具（包括 MCP 工具），本工具负责转发与展示。
+ * 你自己的 AI 工具可直接 import src/hermes.js 使用。
+ */
+import readline from 'node:readline';
+import { chat, listModels, summarizeChoice } from './hermes.js';
+import { loadEnv } from './config.js';
+
+function printHelp() {
+  console.log(`
+ym-hermes-desktop — Hermes 接入点客户端
+  Hermes 地址: ${loadEnv().endpoint || '(未配置)'}   模型: ${loadEnv().model}
+
+  （直接输入问题，回车后由 Hermes 执行并回答）
+  /models   查看模型列表
+  /check    检查接入点连通性
+  /help     显示帮助
+  /exit     退出
+`);
+}
+
+async function checkHealth() {
+  try {
+    const models = await listModels();
+    console.log(`✓ Hermes 接入点正常，模型: ${models.join(', ')}`);
+  } catch (err) {
+    console.log(`✗ Hermes 接入点不可用: ${err.message}`);
+    console.log('  请确认 Hermes API server 已启动（hermes gateway status / 8642 端口可访问）');
+  }
+}
+
+async function askOnce(question) {
+  const result = await chat({ messages: [{ role: 'user', content: question }] });
+  const choice = result.choices && result.choices[0];
+  if (!choice) return console.log('(无返回结果)');
+  console.log(summarizeChoice(choice));
+}
+
+async function main() {
+  const args = process.argv.slice(2);
+
+  if (args.includes('--models')) {
+    try {
+      console.log((await listModels()).join('\n'));
+    } catch (err) {
+      console.log(`✗ ${err.message}`);
+    }
+    process.exit(0);
+  }
+  if (args.includes('--check')) {
+    await checkHealth();
+    process.exit(0);
+  }
+  // 单次提问模式: node src/index.js --ask "问题"
+  const askIdx = args.indexOf('--ask');
+  if (askIdx !== -1) {
+    const q = args[askIdx + 1];
+    if (!q) return console.log('用法: --ask "你的问题"');
+    try {
+      await askOnce(q);
+    } catch (err) {
+      console.log(`✗ ${err.message}`);
+    }
+    process.exit(0);
+  }
+
+  await checkHealth();
+  printHelp();
+
+  const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+  rl.setPrompt('hermes> ');
+  rl.prompt();
+
+  let chain = Promise.resolve();
+  rl.on('line', (line) => {
+    chain = chain
+      .then(async () => {
+        const input = line.trim();
+        if (!input) return;
+        if (input === '/exit' || input === '/quit') {
+          rl.close();
+          process.exit(0);
+        } else if (input === '/help') {
+          printHelp();
+        } else if (input === '/models') {
+          try {
+            console.log((await listModels()).join('\n'));
+          } catch (err) {
+            console.log(`✗ ${err.message}`);
+          }
+        } else if (input === '/check') {
+          await checkHealth();
+        } else {
+          try {
+            await askOnce(input);
+          } catch (err) {
+            console.log(`✗ ${err.message}`);
+          }
+        }
+      })
+      .then(() => rl.prompt());
+  });
+}
+
+main().catch((err) => {
+  console.error('启动失败:', err.message);
+  process.exit(1);
+});

package/src/mcp-server.js

@@ -0,0 +1,92 @@
+#!/usr/bin/env node
+/**
+ * mcp-server.js — 把 Hermes 能力暴露为 MCP server（stdio 传输）
+ *
+ * 任何 MCP 客户端（Cursor / Claude Desktop / Cherry Studio 等）连接本 server 后，
+ * 可通过 hermes_chat 工具让 Hermes 执行任务（Hermes 会自行调度其注册的工具/MCP）。
+ *
+ * 客户端配置：
+ * {
+ *   "mcpServers": {
+ *     "ym-hermes": {
+ *       "command": "npx",
+ *       "args": ["-y", "ym-hermes-desktop", "ym-hermes-mcp"],
+ *       "env": {
+ *         "HERMES_API_ENDPOINT": "http://127.0.0.1:8642/v1",
+ *         "HERMES_API_KEY": "你的 Bearer token",
+ *         "HERMES_MODEL": "hermes-agent"
+ *       }
+ *     }
+ *   }
+ * }
+ */
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import {
+  ListToolsRequestSchema,
+  CallToolRequestSchema,
+} from '@modelcontextprotocol/sdk/types.js';
+import { chat } from './hermes.js';
+import { loadEnv } from './config.js';
+
+const server = new Server(
+  { name: 'ym-hermes-desktop', version: '1.0.0' },
+  { capabilities: { tools: {} } }
+);
+
+const TOOLS = [
+  {
+    name: 'hermes_chat',
+    description:
+      '向 Hermes Agent 发送对话并获取回复。Hermes 会自动执行它已注册的工具（含 MCP 工具）来完成你的请求。',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        question: {
+          type: 'string',
+          description: '要 Hermes 处理的问题或任务描述（与 messages 二选一）',
+        },
+        messages: {
+          type: 'array',
+          description: '完整对话消息数组，如 [{"role":"user","content":"..."}]（与 question 二选一）',
+          items: {
+            type: 'object',
+            properties: {
+              role: { type: 'string', enum: ['system', 'user', 'assistant'] },
+              content: { type: 'string' },
+            },
+          },
+        },
+      },
+    },
+  },
+];
+
+server.setRequestHandler(ListToolsRequestSchema, async () => ({ tools: TOOLS }));
+
+server.setRequestHandler(CallToolRequestSchema, async (request) => {
+  const { name, arguments: args } = request.params;
+  if (name !== 'hermes_chat') {
+    throw new Error(`Unknown tool: ${name}`);
+  }
+  const messages =
+    args.messages || (args.question ? [{ role: 'user', content: String(args.question) }] : null);
+  if (!messages) {
+    throw new Error('缺少参数：请提供 question 或 messages');
+  }
+  const result = await chat({ messages });
+  const content =
+    result?.choices?.[0]?.message?.content ?? JSON.stringify(result ?? '');
+  return { content: [{ type: 'text', text: String(content) }] };
+});
+
+// 启动前给出接入点检查提示（缺失配置时输出到 stderr，不干扰 MCP 协议）
+const { endpoint, apiKey } = loadEnv();
+if (!endpoint || !apiKey) {
+  process.stderr.write(
+    '[ym-hermes] 警告: 未配置 HERMES_API_ENDPOINT / HERMES_API_KEY，调用 hermes_chat 将失败\n'
+  );
+}
+
+const transport = new StdioServerTransport();
+await server.connect(transport);