Hillnote MCP服务器
](https://www.npmjs.com/package/@hillnote/mcp-server)    ](https://nodejs.org)
官方 模型上下文协议(MCP) 服务器 Hillnote,使AI助手能够以编程方式与您的文档工作区进行交互。
平台支持: 支持 macOS, 视窗,以及 Linux.
特性
- 📁 多工作区支持 -管理多个文档工作区
- 📝 文档管理 -文档的完整CRUD操作
- 🔍 智能搜索 -模糊搜索,在标题、标签和内容之间进行智能排名
- ✏️ 内容操纵 -具有验证和预览功能的高级内容编辑
- 🎯 AI食谱 -管理和执行AI提示食谱
- 🛠️ HTML工具 -创建基于HTML的交互式实用程序
- 📋 数据库和任务管理 -创建具有行、列、视图和看板的数据库,用于任务跟踪
- 🎨 幻灯片演示 -使用讲故事指南和视觉设计工具进行两阶段幻灯片创作
- 🎨 画布绘画 -创建和编辑带有形状、文本、箭头等的Excalidraw画布绘图
- 🏷️ 元数据支持 -包含标签、表情符号和描述的丰富文档元数据
需求
- macOS, 视窗,或 Linux
- Hillnote桌面应用程序
- Node.js >= 18.0.0
- MCP兼容客户端 (克劳德桌面、光标、VS代码等)
安装
选项1:从NPM安装(推荐)
# Install globally (IMPORTANT: Use -g flag!)
npm install -g @hillnote/mcp-server
# Verify installation worked
npm list -g @hillnote/mcp-server
# If using Homebrew Node.js, the files will be in:
# /opt/homebrew/lib/node_modules/@hillnote/mcp-server/⚠️ 重要提示: 这 -g 全局安装需要标志。没有它,该软件包将在本地安装,无法与Claude Desktop配置一起使用。
选项2:从源代码安装
# Clone the repository
git clone https://github.com/HillnoteApp/hillnote-mcp-server.git
cd hillnote-mcp-server
# Install dependencies (NO -g flag needed here)
npm install更新到最新版本
NPM安装
# Update to the latest version
npm update -g @hillnote/mcp-server
# Or reinstall to force latest version
npm install -g @hillnote/mcp-server@latest
# Check current version
npm list -g @hillnote/mcp-server
# After updating, restart your MCP client (Claude Desktop, Cursor, etc.)源安装
# Navigate to your cloned repository
cd /path/to/hillnote-mcp-server
# Pull latest changes
git pull origin main
# Reinstall dependencies
npm install
# After updating, restart your MCP client版本检查
要查看您当前运行的版本,请执行以下操作:
# For NPM installation
npm list -g @hillnote/mcp-server
# For source installation
cd /path/to/hillnote-mcp-server
cat package.json | grep version故障排除更新
如果您在更新后遇到问题:
- 清除npm缓存:
npm cache clean --force- 卸载并重新安装:
npm uninstall -g @hillnote/mcp-server
npm install -g @hillnote/mcp-server- 完全重新启动MCP客户端 (不仅仅是重新加载-完全退出并重新打开)
配置
MCP服务器会自动从应用程序的配置中发现您的所有Hillnote工作区:
- macOS:
~/Library/Application Support/Hillnote/workspaces.json - 窗户:
%APPDATA%/Hillnote/workspaces.json - Linux:
~/.config/Hillnote/workspaces.json
配置示例
NPM安装
如果通过NPM安装,请使用全局节点模块路径:
{
"mcpServers": {
"hillnote": {
"command": "hillnote-mcp"
}
}
}通过以下方式找到你的路: npm root -g
源安装
如果从GitHub克隆:
{
"mcpServers": {
"hillnote": {
"command": "node",
"args": ["/path/to/hillnote-mcp-server/index.js"]
}
}
}客户端特定配置
Claude Desktop
地点: ~/Library/Application Support/Claude/claude_desktop_config.json
将上述配置添加到此文件中。
Cursor
位置:设置→ 特性→ MCP
将上述配置添加到MCP服务器部分。
VS Code
安装MCP扩展,并将配置添加到您的settings.json或扩展配置中。
可用工具
📁 工作空间管理
list_workspaces
列出所有可用的工作区,包括文档计数和元数据。
// No input required
// Returns: Array of workspace objects with path, name, overview, and documentCountread_registry
获取完整的工作区概述,包括所有文档、文件夹和关系。
// Input: { workspace: "workspace-name" }
// Returns: Complete registry with documents and folder structure📄 文档操作
read_document
读取特定文档的内容和元数据。
// Input: { workspace: "workspace-name", documentId: "doc-id" }
// Returns: Document content, metadata, and frontmatteradd_document
使用内容和元数据创建新文档。
// Input: {
// workspace: "workspace-name",
// name: "Document Name",
// content: "Document content",
// emoji: "📄",
// description: "Brief description",
// parent: "optional-folder-id"
// }
// Returns: { success: true, documentId: "new-id", fileName: "document-name.md" }update_document
更新现有文档的内容或元数据。
// Input: {
// workspace: "workspace-name",
// documentId: "doc-id",
// content: "New content",
// name: "New Name",
// emoji: "📝",
// description: "Updated description"
// }
// Returns: { success: true }rename_document
重命名文档并更新其文件名。
// Input: { workspace: "workspace-name", documentId: "doc-id", newTitle: "New Title" }
// Returns: { success: true, newFileName: "new-title.md" }delete_document
从工作区中删除文档。
// Input: { workspace: "workspace-name", documentId: "doc-id" }
// Returns: { success: true }🔍 搜索
search_documents
使用模糊匹配和智能排名搜索文档。
// Input: {
// query: "search term",
// workspace: "optional-workspace",
// fuzzy: true,
// threshold: 0.6,
// limit: 10
// }
// Returns: Ranked search results with snippets and scores✏️ 内容操纵
insert_content
在特定位置插入内容并进行验证。
// Input: {
// workspace: "workspace-name",
// documentId: "doc-id",
// position: "start" | "end" | number | { line: number } | { after: "heading" },
// text: "Content to insert",
// validate: true,
// preview: true
// }
// Returns: { success: true, preview: "...", validation: {...} }replace_content
用预览和出现信息替换文档中的文本。
// Input: {
// workspace: "workspace-name",
// documentId: "doc-id",
// searchText: "text to find",
// replaceText: "replacement text",
// all: false,
// caseSensitive: false,
// wholeWord: false,
// useRegex: false
// }
// Returns: { success: true, replacements: 1, preview: "..." }delete_content
删除位置或图案之间的内容。
// Input: {
// workspace: "workspace-name",
// documentId: "doc-id",
// startPos: 0 | { line: 5 } | { pattern: "## Section" },
// endPos: 100 | { line: 10 } | { pattern: "## Next Section" }
// }
// Returns: { success: true, deletedChars: 95, preview: "..." }append_to_section
将内容附加到特定的标记部分。
// Input: {
// workspace: "workspace-name",
// documentId: "doc-id",
// sectionHeading: "## Notes",
// content: "Additional notes"
// }
// Returns: { success: true }🎯 AI配方管理
食谱是人工智能提示覆盖,当用户的请求与特定主题匹配时,会触发自定义指令。
list_recipes
列出工作区中的所有AI提示食谱。
// Input: { workspacePath: "/path/to/workspace" }
// Returns: Array of recipe objects with metadataget_recipe
按ID获取特定食谱。
// Input: { workspacePath: "/path/to/workspace", recipeId: "recipe-id" }
// Returns: Complete recipe with trigger, instructions, and document referencescreate_recipe
创建新的AI提示配方。
// Input: {
// workspacePath: "/path/to/workspace",
// recipe: {
// when_user_asks_about: "quarterly reports",
// override_instructions: "Use the company template and include KPIs...",
// required_documents: ["documents/template.md"],
// optional_documents: ["documents/past-reports.md"],
// output_format: "markdown"
// }
// }
// Returns: { success: true, recipe: { id: "recipe_...", ... } }update_recipe
更新现有配方。
// Input: {
// workspacePath: "/path/to/workspace",
// recipeId: "recipe-id",
// updates: {
// when_user_asks_about: "updated trigger",
// override_instructions: "updated instructions"
// }
// }
// Returns: { success: true }get_recipe_documents
加载配方引用的文档内容。
// Input: { workspacePath: "/path/to/workspace", recipeId: "recipe-id", includeOptional: true }
// Returns: { recipe: {...}, documents: { required: [...], optional: [...] } }📋 数据库和任务管理
数据库是包含markdown文件(行)的灵活文件夹,具有 database.json 配置。它们可以通过添加以下内容用作任务板 status 带有看板视图的列。
create_database
在工作区中创建新数据库。
// Input: {
// workspace: "workspace-name",
// name: "Project Tasks",
// columns: [
// { id: "title", name: "Title", type: "title" },
// { id: "status", name: "Status", type: "status",
// options: ["To Do", "In Progress", "Done", "Archived"],
// optionColors: { "To Do": "gray", "In Progress": "amber", "Done": "emerald", "Archived": "purple" },
// optionStates: { "To Do": "normal", "In Progress": "normal", "Done": "done", "Archived": "archive" }
// },
// { id: "priority", name: "Priority", type: "select", options: ["Low", "Medium", "High"] },
// { id: "recurring", name: "Recurring", type: "recurring" }
// ],
// views: [
// { id: "kanban", name: "Board", type: "kanban", groupBy: "status" },
// { id: "table", name: "Table", type: "table" }
// ],
// defaultView: "kanban",
// folderPath: "optional/subfolder"
// }
// Returns: { success: true, name: "...", path: "..." }列类型: title, text, number, select, multiselect, status, checkbox, date, url, email, recurring
状态栏 支持 optionStates 将每个选项映射到 "normal", "done" (删除线),或 "archive" (变暗)——启用看板行为。
重复列 支持每日/每周/每月/每年自动重置任务。
read_database
使用可选的过滤、排序和搜索读取数据库。
// Input: {
// workspace: "workspace-name",
// databasePath: "Project Tasks",
// search: "optional search query",
// filters: [{ column: "status", operator: "equals", value: "In Progress" }],
// sort: { column: "priority", direction: "desc" },
// viewId: "kanban",
// limit: 50
// }
// Returns: Database config (columns, views) and matching rowslist_databases
列出工作区中的所有数据库。
// Input: { workspace: "workspace-name" }
// Returns: Array of databases with metadata and row countsdelete_database
永久删除数据库及其所有行。
// Input: { workspace: "workspace-name", databasePath: "Project Tasks" }
// Returns: { success: true }add_rows
向数据库添加一行或多行。
// Input: {
// workspace: "workspace-name",
// databasePath: "Project Tasks",
// rows: [
// { title: "Implement feature X", status: "To Do", priority: "High", _content: "Task details..." },
// { title: "Fix bug Y", status: "In Progress", priority: "Medium" }
// ]
// }
// Returns: { success: true, added: [...] }update_rows
按ID(文件路径)或匹配条件更新行。
// Input: {
// workspace: "workspace-name",
// databasePath: "Project Tasks",
// updates: { status: "Done", priority: "Low" },
// ids: ["/path/to/row.md"], // by file path
// where: { status: "In Progress" } // or by criteria
// }
// Returns: { success: true, updated: [...] }delete_rows
按ID或匹配条件删除行。
// Input: {
// workspace: "workspace-name",
// databasePath: "Project Tasks",
// ids: ["/path/to/row.md"],
// where: { status: "Archived" }
// }
// Returns: { success: true }add_column
向数据库添加新列。
// Input: {
// workspace: "workspace-name",
// databasePath: "Project Tasks",
// column: { id: "assignee", name: "Assignee", type: "text" },
// defaultValue: "Unassigned"
// }
// Returns: { success: true }update_column
更新列属性(名称、类型、选项、颜色、状态)。
// Input: {
// workspace: "workspace-name",
// databasePath: "Project Tasks",
// columnId: "status",
// updates: { options: ["To Do", "In Progress", "Review", "Done"] }
// }
// Returns: { success: true }delete_column
从数据库中删除列和所有行。
// Input: { workspace: "workspace-name", databasePath: "Project Tasks", columnId: "priority" }
// Returns: { success: true }create_view
使用过滤器、排序和显示选项创建已保存的视图。
// Input: {
// workspace: "workspace-name",
// databasePath: "Project Tasks",
// view: {
// name: "Active Tasks",
// type: "kanban", // table, kanban, gallery, chart
// groupBy: "status",
// filters: [{ column: "status", operator: "notEquals", value: "Archived" }],
// sorts: [{ column: "priority", direction: "desc" }]
// }
// }
// Returns: { success: true, viewId: "..." }list_views
列出数据库的所有已保存视图。
// Input: { workspace: "workspace-name", databasePath: "Project Tasks" }
// Returns: Array of view configurations🎨 幻灯片演示
幻灯片使用两阶段的工作流程:先写故事,然后添加视觉设计。
get_slides_story_guide
获取8种经过验证的技巧(英雄之旅、闪闪发光、媒体研究等)的故事讲述指南。
// No input required
// Returns: Story-writing guide with narrative techniques and structure advice
// Important: Do NOT use any visual layout markers (~split, ~inline, ~bg-, etc.) during this phaseget_slides_visual_guide
获取添加布局标记、图像、图表和示意图的视觉设计指南。
// Input: { documentPath: "documents/my-presentation.slides.md" }
// Returns: Visual design guide with layout markers, chart types, mermaid diagrams, and examples
// Note: Requires the .slides.md file to already exist (proves story has been drafted)重要提示: 使用创建幻灯片时 add_document,标题必须以结尾 .slides.md (例如,“我的演示文稿.slides.md”)。这 .slides.md 扩展使其成为幻灯片演示文稿。
工作流程示例:
// 1. Get the story guide first
get_slides_story_guide()
// 2. Create the slide presentation (story content only, no visual markers)
add_document({
workspace: "workspace-name",
name: "Quarterly Review.slides.md", // Note: ends with .slides.md
content: `---
type: slides
theme: minimal
---
# Quarterly Review
Q4 2024 Results
***
# Key Metrics
- Revenue: $1.2M
- Growth: 25%
- Users: 10,000+
`
})
// 3. Get the visual guide and enhance slides in batches of 3-5
get_slides_visual_guide({ documentPath: "documents/quarterly-review.slides.md" })
// Then edit the file to add ~split, ~inline, ~bg-, images, charts, etc.🎨 画布绘画
get_canvas_guide
获取在Hillnote中创建和编辑Excalidraw画布绘图的全面指南。
// No input required
// Returns: Complete guide with element types, layout planning, spacing rules, colors, and best practices重要提示: 使用以下命令创建画布时 add_document,标题必须以结尾 .canvas.md (例如,“架构图.pcanvas.md”)。不提供内容——系统会自动生成内容。
read_canvas
读取并解析画布文件,返回所有元素的结构化描述。
// Input: { workspace: "workspace-name", canvasPath: "documents/my-drawing.canvas.md" }
// Returns: { canvasPath: "...", elementCount: 5, elements: [...] }add_canvas_elements
将形状、文本、箭头和其他元素添加到画布文件中。
// Input: {
// workspace: "workspace-name",
// canvasPath: "documents/my-drawing.canvas.md",
// elements: [
// { type: "rectangle", x: 0, y: 0, width: 200, height: 100, label: "Start", backgroundColor: "#a5d8ff" },
// { type: "arrow", x: 200, y: 50, points: [[0, 0], [100, 0]] },
// { type: "rectangle", x: 300, y: 0, width: 200, height: 100, label: "End", backgroundColor: "#b2f2bb" },
// { type: "text", x: 0, y: 120, text: "My Diagram", fontSize: 28 }
// ]
// }
// Returns: { success: true, added: 4, totalElements: 4, elementIds: [...] }支持的元素类型: rectangle, ellipse, diamond, text, arrow, line
元素属性:
- 位置/尺寸:
x,y,width,height - 造型:
strokeColor,backgroundColor,fillStyle(实心/空心/十字纹),strokeWidth,roughness(0-2),opacity(0-100) - 文本:
text,fontSize,fontFamily(1=维吉尔,2=赫尔维蒂卡,3=卡斯卡迪亚,5=埃克斯卡利字体),textAlign - 箭头/线条:
points(例如。,[[0,0],[200,100]]),startArrowhead,endArrowhead - 形状:
label(矩形/椭圆/菱形内居中的文本) - 分组:
groupId
clear_canvas
从画布文件中删除所有元素,得到一张白纸。
// Input: { workspace: "workspace-name", canvasPath: "documents/my-drawing.canvas.md" }
// Returns: { success: true, message: "All elements cleared from canvas" }工作流程示例:
// 1. Get the canvas guide first
get_canvas_guide()
// 2. Create a new canvas
add_document({
workspace: "workspace-name",
name: "Architecture Diagram.canvas.md" // Note: ends with .canvas.md, no content needed
})
// 3. Add elements to the canvas
add_canvas_elements({
workspace: "workspace-name",
canvasPath: "documents/architecture-diagram.canvas.md",
elements: [
{ type: "text", x: 0, y: 0, text: "System Architecture", fontSize: 28 },
{ type: "rectangle", x: 0, y: 50, width: 200, height: 80, label: "Frontend", backgroundColor: "#a5d8ff" },
{ type: "arrow", x: 200, y: 90, points: [[0, 0], [100, 0]] },
{ type: "rectangle", x: 300, y: 50, width: 200, height: 80, label: "Backend", backgroundColor: "#b2f2bb" }
]
})
// 4. To redraw from scratch
clear_canvas({ workspace: "workspace-name", canvasPath: "documents/architecture-diagram.canvas.md" })
// Then add_canvas_elements again with new elements🛠️ HTML工具管理
add_html_tool
在工作区中创建交互式HTML工具。
// Input: {
// workspacePath: "/path/to/workspace",
// toolName: "calculator",
// description: "Scientific calculator",
// category: "utilities", // optional
// files: [
// { filename: "index.html", content: "...", isEntryPoint: true },
// { filename: "styles.css", content: "body { ... }" },
// { filename: "script.js", content: "// JS code" }
// ]
// }
// Returns: { success: true, path: "resources/html/calculator", entryPoint: "index.html", markdownLink: "[html:calculator](...)" }edit_html_tool
编辑现有HTML工具中的文件(创建、更新或删除文件)。
// Input: {
// workspacePath: "/path/to/workspace",
// toolName: "calculator",
// category: "utilities", // optional
// operations: [
// { action: "update", filename: "index.html", content: "..." },
// { action: "create", filename: "utils.js", content: "// new file" },
// { action: "delete", filename: "old-file.js" }
// ],
// updateMetadata: { description: "Updated calculator" }
// }
// Returns: { success: true, changes: { created: [...], updated: [...], deleted: [...] } }add_tool_to_doc
在文档中插入HTML工具引用。
// Input: {
// workspacePath: "/path/to/workspace",
// documentPath: "documents/my-doc.md",
// toolName: "calculator",
// displayName: "My Calculator", // optional
// position: "end" // "end", "beginning", or "after:"
// }
// Returns: { success: true, toolLink: "[html:My Calculator](...)" }list_html_tools
列出工作区中的所有HTML工具。
// Input: { workspacePath: "/path/to/workspace", category: "utilities" }
// Returns: Array of HTML tools with metadata and markdown linksget_html_tool
获取特定HTML工具的详细信息和文件。
// Input: { workspacePath: "/path/to/workspace", toolName: "calculator", category: "utilities" }
// Returns: Tool info with all file contents, entry point, and markdown linkread_html_file
读取HTML工具中特定文件的内容。
// Input: { workspacePath: "/path/to/workspace", filePath: "resources/html/calculator/index.html" }
// Returns: { filePath: "...", content: "..." }write_html_file
在HTML工具文件夹中编写或创建文件。
// Input: { workspacePath: "/path/to/workspace", filePath: "resources/html/calculator/style.css", content: "body { ... }" }
// Returns: { success: true, filePath: "..." }replace_in_html_file
查找并替换HTML工具文件中的文本。
// Input: {
// workspacePath: "/path/to/workspace",
// filePath: "resources/html/calculator/index.html",
// searchText: "Old Title",
// replaceText: "New Title"
// }
// Returns: { success: true, filePath: "..." }工作区结构
Hillnote工作区通常存储在您的Documents文件夹或自定义位置:
~/Documents/YourWorkspace/
├── readme.md # Workspace overview
├── documents-registry.json # Document metadata
├── ai_prompt_overrides.json # AI prompt recipes/overrides
├── documents/ # Markdown documents and databases
│ ├── document-1.md
│ ├── folder/
│ │ └── document-2.md
│ └── Project Tasks/ # Database (e.g., task board)
│ ├── database.json # Database configuration (columns, views)
│ ├── implement-feature-x.md # Row (task) with frontmatter
│ └── fix-bug-y.md # Row (task) with frontmatter
└── resources/ # Assets and tools
├── images/ # Image attachments
└── html/ # HTML tools
└── tool-name/
├── index.html
└── assets/文档格式
文档使用Markdown和YAML frontmatter:
---
title: Document Title
tags: [tag1, tag2]
emoji: 📄
description: Brief description
created: 2024-01-01T00:00:00Z
modified: 2024-01-02T00:00:00Z
---
# Document Title
Your content here...发展
项目结构
mcp-server/
├── index.js # Main server entry point
├── config.json # Server configuration
├── package.json # Dependencies
├── src/
│ ├── tools/
│ │ ├── index.js # Tool aggregator
│ │ ├── workspace.js # Workspace tools
│ │ ├── document.js # Document tools
│ │ ├── content.js # Content manipulation
│ │ ├── search.js # Search tools
│ │ ├── recipe.js # Recipe management
│ │ ├── html-tool.js # HTML tool management
│ │ ├── database.js # Database, row, column, and view management
│ │ ├── slides.js # Slide presentation guides (story + visual)
│ │ └── canvas.js # Excalidraw canvas drawings
│ └── utils/
│ └── helpers.js # Utility functions
└── README.md添加新工具
- 在中创建新的工具文件
src/tools/ - 导出工具定义和处理程序
- 导入
src/tools/index.js - MCP客户端可以自动使用工具
在发展中奔跑
# Enable watch mode
npm run dev
# Run the server
npm start错误处理
所有工具都使用结构化错误响应:
InvalidParams:参数缺失或无效InternalError:服务器端错误MethodNotFound:未知工具名称
安全
- 文件操作被沙盒化到工作区目录
- 未发出网络请求
- 包括路径遍历保护
- 所有操作的输入验证
许可证
麻省理工学院-参见 许可证 文件
支持
- 问题:
- 电子邮件: support@hillnote.com
- 文档: Hillnote文档
______________________________________________________________________
建于❤️ 作者:Rajath Bail
