@__shiyi/yinxiang-mcp 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 HL
+
+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,56 @@
+# yinxiang-mcp
+
+印象笔记（Yinxiang / Evernote China）的 MCP server。通过 stdio 提供笔记读写工具，支持 Markdown 与 ENML 互转。
+
+## 安装
+
+```bash
+npx -y @__shiyi/yinxiang-mcp
+```
+
+## 认证
+
+Direct Token 模式，不走 OAuth。需要两个环境变量：
+
+- `YINXIANG_DEV_TOKEN` — Developer Token，在 <https://dev.yinxiang.com> 申请
+- `YINXIANG_NOTESTORE_URL` — NoteStore URL，如 `https://app.yinxiang.com/shard/s68/notestore`
+
+## 接入 Claude
+
+```json
+{
+  "mcpServers": {
+    "yinxiang": {
+      "command": "npx",
+      "args": ["-y", "@__shiyi/yinxiang-mcp"],
+      "env": {
+        "YINXIANG_DEV_TOKEN": "<token>",
+        "YINXIANG_NOTESTORE_URL": "https://app.yinxiang.com/shard/sXX/notestore"
+      }
+    }
+  }
+}
+```
+
+## 工具
+
+- `list-notebooks` — 列出笔记本
+- `find-notes`（`words`, `notebookGuid`, `maxResults`）— 搜索笔记
+- `create-note`（`title`, `content`, `notebookGuid`）— 新建笔记，Markdown 转 ENML
+- `get-note`（`guid`）— 读取笔记，ENML 转 Markdown
+
+## 本地开发
+
+```bash
+npm install
+cp .env.example .env
+npm run verify     # 连通性验证
+npm run test-rw    # 读写 round-trip 测试
+npm start
+```
+
+## 限制
+
+- `evernote@2.0.5`，EDAM API 偏旧
+- Markdown 转换覆盖基础语法；任务列表、附件暂不支持
+- MIT

package/enml.mjs

@@ -0,0 +1,52 @@
+/**
+ * @file enml.mjs
+ * @brief Markdown ↔ ENML(Evernote Note Markup Language)双向转换。
+ *
+ * @details 基础版:marked(MD→HTML)+ turndown(HTML→MD),
+ *          覆盖 标题/段落/列表/代码块/加粗斜体/链接/图片。
+ *          任务列表(<en-todo>)、附件资源(resource)等高级特性后续迭代。
+ */
+
+import { marked } from 'marked';
+import TurndownService from 'turndown';
+
+const turndown = new TurndownService({
+  headingStyle: 'atx',
+  codeBlockStyle: 'fenced',
+  bulletListMarker: '-',
+});
+
+/**
+ * @brief 清理 HTML 为 ENML 可接受的 XHTML 子集。
+ * @note 去掉 class/id/data-* 等属性(ENML 可能拒绝), void 标签自闭合。
+ * @param {string} html
+ * @returns {string}
+ */
+function sanitizeEnml(html) {
+  return html
+    .replace(/\s+(class|id|target|rel|data-[a-z-]+)="[^"]*"/gi, '')
+    .replace(/<br\s*>/gi, '<br/>')
+    .replace(/<hr\s*>/gi, '<hr/>')
+    .replace(/<img([^>]*?)>/gi, '<img$1/>');
+}
+
+/**
+ * @brief Markdown → 完整 ENML 文档。
+ * @param {string} md Markdown 源文
+ * @returns {string} ENML(含 XML 声明与 <en-note> 根)
+ */
+export function mdToEnml(md) {
+  const html = marked.parse(md);
+  return `<?xml version="1.0" encoding="UTF-8"?>\n<!DOCTYPE en-note SYSTEM "http://xml.evernote.com/pub/enml2.dtd">\n<en-note>${sanitizeEnml(html)}</en-note>`;
+}
+
+/**
+ * @brief ENML 文档 → Markdown。
+ * @param {string} enml Evernote note.content
+ * @returns {string} Markdown
+ */
+export function enmlToMd(enml) {
+  const m = String(enml).match(/<en-note[^>]*>([\s\S]*?)<\/en-note>/i);
+  const inner = m ? m[1] : String(enml);
+  return turndown.turndown(inner).trim();
+}

package/index.mjs

@@ -0,0 +1,181 @@
+#!/usr/bin/env node
+/**
+ * @file index.mjs
+ * @brief 印象笔记 MCP Server (stdio), Direct Token 模式。
+ *
+ * @details Developer Token + NoteStore URL 直连。工具:
+ *          list-notebooks / find-notes (只读)
+ *          create-note   / get-note     (Markdown ↔ ENML 读写)
+ */
+
+import { createRequire } from 'node:module';
+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 { mdToEnml, enmlToMd } from './enml.mjs';
+
+const require = createRequire(import.meta.url);
+const Evernote = require('evernote');
+const { NoteStoreClient } = require('evernote/lib/stores');
+
+const TOKEN = process.env.YINXIANG_DEV_TOKEN;
+const NOTESTORE_URL = process.env.YINXIANG_NOTESTORE_URL;
+
+if (!TOKEN || !NOTESTORE_URL) {
+  console.error('[yinxiang-mcp] 缺少环境变量 YINXIANG_DEV_TOKEN 或 YINXIANG_NOTESTORE_URL。请在 MCP 客户端的 env 中配置。');
+  process.exit(1);
+}
+
+/** @brief NoteStoreClient 单例, Direct Token 直连。 */
+const noteStore = new NoteStoreClient({ token: TOKEN, url: NOTESTORE_URL });
+
+/**
+ * @brief 将执行错误封装为 MCP 错误结果。
+ * @param {unknown} err
+ * @returns {{ content: Array, isError: true }}
+ */
+function toolError(err) {
+  const msg = err && err.message ? err.message : String(err);
+  const edam = err && err.errorCode ? ` (EDAM errorCode=${err.errorCode})` : '';
+  return {
+    content: [{ type: 'text', text: `调用失败: ${msg}${edam}` }],
+    isError: true,
+  };
+}
+
+/** @brief list-notebooks */
+async function listNotebooks() {
+  const notebooks = await noteStore.listNotebooks();
+  const data = notebooks.map((nb) => ({ name: nb.name, guid: nb.guid }));
+  return {
+    content: [{ type: 'text', text: JSON.stringify({ count: data.length, notebooks: data }, null, 2) }],
+  };
+}
+
+/** @brief find-notes */
+async function findNotes({ words, notebookGuid, maxResults }) {
+  const filter = new Evernote.NoteStore.NoteFilter({
+    ...(words ? { words } : {}),
+    ...(notebookGuid ? { notebookGuid } : {}),
+  });
+  const spec = new Evernote.NoteStore.NotesMetadataResultSpec({
+    includeTitle: true,
+    includeCreated: true,
+    includeUpdated: true,
+    includeNotebookGuid: true,
+    includeTagGuids: true,
+  });
+  const max = Math.min(Math.max(Number(maxResults) || 10, 1), 50);
+  const result = await noteStore.findNotesMetadata(filter, 0, max, spec);
+  const notes = result.notes.map((n) => ({
+    title: n.title,
+    guid: n.guid,
+    notebookGuid: n.notebookGuid,
+    created: n.created,
+    updated: n.updated,
+  }));
+  return {
+    content: [{ type: 'text', text: JSON.stringify({ total: result.totalNotes, returned: notes.length, notes }, null, 2) }],
+  };
+}
+
+/** @brief create-note: Markdown content → ENML → createNote。 */
+async function createNote({ title, content, notebookGuid }) {
+  const note = new Evernote.Types.Note({
+    title,
+    content: mdToEnml(content),
+    ...(notebookGuid ? { notebookGuid } : {}),
+  });
+  const created = await noteStore.createNote(note);
+  return {
+    content: [{ type: 'text', text: JSON.stringify({ guid: created.guid, title: created.title }, null, 2) }],
+  };
+}
+
+/** @brief get-note: getNote → ENML → Markdown。 */
+async function getNote({ guid }) {
+  // @note 5 个非 token 参数须全传, 否则 makeProxyMine 校验失败。
+  const note = await noteStore.getNote(guid, true, false, false, false);
+  const md = enmlToMd(note.content);
+  return {
+    content: [{ type: 'text', text: `# ${note.title}\n\nguid: ${note.guid}\n\n---\n\n${md}` }],
+  };
+}
+
+const server = new Server(
+  { name: 'yinxiang-mcp', version: '0.2.0' },
+  { capabilities: { tools: {} } },
+);
+
+/** @brief 工具清单。 */
+server.setRequestHandler(ListToolsRequestSchema, () => ({
+  tools: [
+    {
+      name: 'list-notebooks',
+      description: '列出当前印象笔记账号的所有笔记本(名称与 guid)。',
+      inputSchema: { type: 'object', properties: {} },
+    },
+    {
+      name: 'find-notes',
+      description: '搜索笔记。可按搜索词(words)和/或笔记本(notebookGuid)过滤,返回标题等元数据。',
+      inputSchema: {
+        type: 'object',
+        properties: {
+          words: { type: 'string', description: '搜索词, 支持印象笔记搜索语法(可选)' },
+          notebookGuid: { type: 'string', description: '限定笔记本 guid(可选)' },
+          maxResults: { type: 'number', description: '最大返回条数(1-50), 默认 10', default: 10 },
+        },
+      },
+    },
+    {
+      name: 'create-note',
+      description: '创建一条笔记, content 为 Markdown(自动转 ENML)。',
+      inputSchema: {
+        type: 'object',
+        properties: {
+          title: { type: 'string', description: '笔记标题' },
+          content: { type: 'string', description: '正文, Markdown 格式' },
+          notebookGuid: { type: 'string', description: '目标笔记本 guid(可选, 默认进默认笔记本)' },
+        },
+        required: ['title', 'content'],
+      },
+    },
+    {
+      name: 'get-note',
+      description: '按 guid 读取一条笔记, 内容转回 Markdown。',
+      inputSchema: {
+        type: 'object',
+        properties: { guid: { type: 'string', description: '笔记 guid' } },
+        required: ['guid'],
+      },
+    },
+  ],
+}));
+
+/** @brief 工具派发。 */
+server.setRequestHandler(CallToolRequestSchema, async (request) => {
+  const { name, arguments: args } = request.params;
+  try {
+    switch (name) {
+      case 'list-notebooks':
+        return await listNotebooks();
+      case 'find-notes':
+        return await findNotes(args || {});
+      case 'create-note':
+        return await createNote(args || {});
+      case 'get-note':
+        return await getNote(args || {});
+      default:
+        return toolError(`未知工具: ${name}`);
+    }
+  } catch (err) {
+    return toolError(err);
+  }
+});
+
+const transport = new StdioServerTransport();
+await server.connect(transport);
+console.error('[yinxiang-mcp] 已启动 v0.2.0 (Direct Token, 4 工具, stdio)');

package/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "@__shiyi/yinxiang-mcp",
+  "version": "0.2.0",
+  "description": "印象笔记中国版 MCP server (Direct Token, Markdown↔ENML)",
+  "private": false,
+  "type": "module",
+  "bin": {
+    "yinxiang-mcp": "index.mjs"
+  },
+  "files": [
+    "index.mjs",
+    "enml.mjs",
+    "README.md"
+  ],
+  "scripts": {
+    "verify": "node --env-file=.env verify.mjs",
+    "start": "node index.mjs",
+    "test-rw": "node --env-file=.env test-rw.mjs"
+  },
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "evernote",
+    "yinxiang",
+    "印象笔记",
+    "claude"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/HouiLei/yinxiang-mcp.git"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.29.0",
+    "evernote": "^2.0.5",
+    "marked": "^18.0.5",
+    "turndown": "^7.2.4"
+  }
+}