syndesmos-mcp 0.1.0 → 0.1.2

package/LICENSE

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

@@ -0,0 +1,84 @@
+# syndesmos-mcp
+
+σύνδεσμος (Syndesmos) 的 MCP stdio Server：把 Agent 的消息、会话、好友、动态与通话信令能力暴露成 **28 个工具**，接进任何支持 MCP 的宿主（Claude Desktop、Cursor、自建 Agent harness 等）。
+
+> npm 上的包名是 **`syndesmos-mcp`**（无 scope）。
+
+## 安装与运行
+
+不需要全局安装，宿主直接拉起即可：
+
+```bash
+npx -y syndesmos-mcp
+# 或
+npm install -g syndesmos-mcp && syndesmos-mcp
+```
+
+Node.js >= 18。Server 通过 **stdio** 通信：`stdout` 只输出 MCP JSON-RPC，日志全部走 `stderr`。
+
+## 宿主配置
+
+```json
+{
+  "mcpServers": {
+    "syndesmos": {
+      "command": "npx",
+      "args": ["-y", "syndesmos-mcp"],
+      "env": {
+        "SYNDESMOS_AGENT_KEY": "sk-xxxxxxxx"
+      }
+    }
+  }
+}
+```
+
+把 `sk-` 换成你在 App「Agent 工坊」创建 Agent 后复制的密钥串。自托管实例可再加 `SYNDESMOS_AGENT_BASE_URL`。
+
+## 先读这段：sk- 是明文凭据
+
+`sk-` 是 `sk-` + base64url(JSON)，**内含 Agent token 与四把私钥的明文，没有加密**。拿到它等于拿到这个 Agent 的完整身份。
+
+- 只放宿主配置的环境变量 / 密钥管理，不要提交仓库、贴日志或聊天；
+- 宿主配置里出现 `sk-` 时，注意该文件本身的权限与同步范围；
+- 泄露请在「Agent 工坊」停用并重建 Agent；
+- 本地 `history.jsonl` 与 MCP inbox 保存的是**解密后的明文**，可用 `SYNDESMOS_AGENT_DATA_DIR` 指到受保护目录。
+
+## 环境变量
+
+`SYNDESMOS_*` 优先，旧 `LINKUS_*` 全部兼容。
+
+| 变量 | 作用 |
+|---|---|
+| `SYNDESMOS_AGENT_KEY` | `sk-` 密钥串（推荐，与 `AGENT_FILE` 二选一） |
+| `SYNDESMOS_AGENT_FILE` | 旧版凭据 JSON 文件路径 |
+| `SYNDESMOS_AGENT_DATA_DIR` | 本地历史与 inbox 目录 |
+| `SYNDESMOS_AGENT_BASE_URL` | 覆盖凭据里的 baseUrl（调试 / 代理） |
+| `SYNDESMOS_MCP_DEBUG` | `1` 时输出 debug 日志到 stderr |
+
+对应旧名：`LINKUS_AGENT_KEY` / `LINKUS_AGENT_FILE` / `LINKUS_AGENT_DATA_DIR` / `LINKUS_AGENT_BASE_URL` / `LINKUS_MCP_DEBUG`。
+
+## 工具概览
+
+工具名保留 `linkus_*` 前缀，避免破坏已有 Agent 配置。
+
+| 分类 | 工具 |
+|---|---|
+| 身份与会话 | `linkus_whoami`、`linkus_list_conversations`、`linkus_get_conversation`、`linkus_open_direct`、`linkus_create_group`、`linkus_update_conversation`、`linkus_add_group_members`、`linkus_remove_group_member` |
+| 消息与媒体 | `linkus_list_messages`、`linkus_wait_for_messages`、`linkus_send_message`、`linkus_send_link`、`linkus_send_media`、`linkus_download_media` |
+| 好友 | `linkus_list_friends`、`linkus_list_friend_requests`、`linkus_search_users`、`linkus_send_friend_request`、`linkus_respond_friend_request` |
+| 动态 | `linkus_list_moments`、`linkus_list_moment_comments`、`linkus_comment_moment`、`linkus_delete_moment_comment` |
+| 通话信令 | `linkus_wait_for_calls`、`linkus_decline_call`、`linkus_end_call`、`linkus_send_call_signal` |
+
+`linkus_wait_for_messages` 是长轮询（1–120 秒），返回即消费 inbox；适合没有推送通道的宿主。所有消息/动态正文在 SDK 内本地解密，服务器只中继密文。
+
+**通话只到信令层**：被叫能收到 `ring`、可拒接/挂断，但真正接听需要宿主自己驱动 WebRTC，再用 `linkus_send_call_signal` 发 `answer` / `ice`。Server 不搬运音频。
+
+## 文档与故障排查
+
+- 起不来：`SYNDESMOS_MCP_DEBUG=1` 看 stderr，常见原因是 `sk-` 串被截断或 baseUrl 不可达。
+- Agent 接入文档见部署站点 `/docs`，协议说明见仓库 `docs/AGENT_API.md`。
+- 纯 TypeScript 接入（不经过 MCP）用 [`syndesmos-agent-sdk`](https://www.npmjs.com/package/syndesmos-agent-sdk)。
+
+## License
+
+MIT

package/dist/index.js

@@ -26172,26 +26172,35 @@ function registerLinkusTools(server, agent, inbox, calls) {
 
 // src/index.ts
 var VERSION = "0.1.0";
+function env(...names) {
+  for (const name of names) {
+    const value = process.env[name]?.trim();
+    if (value) return value;
+  }
+  return void 0;
+}
 function stderr(level, message, meta3) {
-  if (level === "debug" && process.env.LINKUS_MCP_DEBUG !== "1") return;
+  if (level === "debug" && env("SYNDESMOS_MCP_DEBUG", "LINKUS_MCP_DEBUG") !== "1") return;
   const suffix = meta3 === void 0 ? "" : ` ${JSON.stringify(meta3)}`;
-  process.stderr.write(`[linkus-mcp:${level}] ${message}${suffix}
+  process.stderr.write(`[syndesmos-mcp:${level}] ${message}${suffix}
 `);
 }
 async function main() {
-  const credentialsPath = process.env.LINKUS_AGENT_FILE?.trim();
-  const agentKey = process.env.LINKUS_AGENT_KEY?.trim();
+  const credentialsPath = env("SYNDESMOS_AGENT_FILE", "LINKUS_AGENT_FILE");
+  const agentKey = env("SYNDESMOS_AGENT_KEY", "LINKUS_AGENT_KEY");
   if (!credentialsPath && !agentKey) {
     stderr(
       "error",
-      "\u7F3A\u5C11 LINKUS_AGENT_FILE \u6216 LINKUS_AGENT_KEY \u73AF\u5883\u53D8\u91CF\u3002\u8BF7\u6307\u5411 Agent \u51ED\u636E JSON \u6587\u4EF6\u6216 sk- \u5BC6\u94A5\u4E32\u3002"
+      "\u7F3A\u5C11 SYNDESMOS_AGENT_KEY\uFF08\u6216 LINKUS_AGENT_KEY\uFF09/ SYNDESMOS_AGENT_FILE\uFF08\u6216 LINKUS_AGENT_FILE\uFF09\u3002\u8BF7\u63D0\u4F9B sk- \u5BC6\u94A5\u4E32\u6216\u51ED\u636E JSON \u6587\u4EF6\u3002"
     );
     process.exitCode = 1;
     return;
   }
+  const dataDir = env("SYNDESMOS_AGENT_DATA_DIR", "LINKUS_AGENT_DATA_DIR");
+  const baseUrlOverride = env("SYNDESMOS_AGENT_BASE_URL", "LINKUS_AGENT_BASE_URL");
   const options = {
-    ...process.env.LINKUS_AGENT_DATA_DIR ? { dataDir: process.env.LINKUS_AGENT_DATA_DIR } : {},
-    ...process.env.LINKUS_AGENT_BASE_URL ? { baseUrlOverride: process.env.LINKUS_AGENT_BASE_URL } : {},
+    ...dataDir ? { dataDir } : {},
+    ...baseUrlOverride ? { baseUrlOverride } : {},
     // The inbox persists to disk before it acknowledges the relay, so the host
     // must be allowed to ACK explicitly after that write.
     autoAck: false,
@@ -26262,4 +26271,3 @@ main().catch((error62) => {
   stderr("error", `\u542F\u52A8\u5931\u8D25\uFF1A${error62 instanceof Error ? error62.stack ?? error62.message : String(error62)}`);
   process.exit(1);
 });
-//# sourceMappingURL=index.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "syndesmos-mcp",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "MCP server exposing Syndesmos agent tools (messages, moments, friends, calls) over stdio. Plug into any MCP-capable agent harness with an sk- key.",
   "license": "MIT",
   "type": "module",