AI导哈

笔记管理服务器

一个简单的模型上下文协议（MCP）服务器，为Claude Desktop提供笔记管理功能，支持创建、读取、更新和删除JSON格式的笔记。

  • by balgaly
  • JavaScript
  • 本地部署
  • 更新于
在 GitHub 查看 balgaly/notes-mcp-server

使用说明

备注MCP服务器

一个简单的模型上下文协议（MCP）服务器，为Claude Desktop提供笔记功能。此服务器允许Claude创建、读取、更新和删除存储为JSON文件的笔记。

🎯 目的

该项目是作为理解MCP（模型上下文协议）的实践学习练习而创建的。它表明：

  • 如何从头开始构建MCP服务器
  • TypeScript和Node.js开发
  • 数据持久化的文件系统操作
  • 使用Zod模式进行数据验证
  • 与Claude Desktop集成

✨ 特性

  • 创建笔记：添加带有标题和内容的新笔记
  • 阅读笔记：检索和显示现有笔记
  • 更新备注：修改现有注释的内容
  • 列表注释：查看所有可用注释
  • 删除笔记：永久删除笔记
  • 永久存储：注释保存为JSON文件 data/ 目录
  • 数据验证：所有笔记数据都使用Zod模式进行验证
  • 错误处理：妥善处理文件系统和验证错误

🛠️ 使用的技术

  • TypeScript：用于类型安全开发
  • Node.js：运行时环境
  • 模型上下文协议SDK：用于MCP服务器功能
  • 萨德：用于数据验证和类型安全
  • 文件系统：用于简单持久化的JSON文件

📁 项目结构

notes-mcp-server/
├── src/
│   └── index.ts          # Main MCP server implementation
├── data/                 # Directory where notes are stored as JSON files
├── build/                # Compiled JavaScript output
├── .vscode/
│   └── mcp.json          # MCP server configuration for VS Code
│   └── tasks.json        # VS Code build tasks
├── .github/
│   └── copilot-instructions.md
├── package.json          # Node.js project configuration
├── tsconfig.json         # TypeScript configuration
├── .gitignore           # Git ignore file
└── README.md            # This file

🚀 入门指南

先决条件

  • Node.js 16或更高版本
  • 克劳德桌面（最新版本）
  • VS代码（可选，用于开发）

安装

  1. 克隆此存储库:

    git clone <repository-url>
cd notes-mcp-server

  2. 安装依赖项:

    npm install

  3. 构建项目:

    npm run build

  4. 在本地测试服务器 （可选）：

    npm run dev

Claude桌面配置

  1. 查找您的Claude Desktop配置文件:

    • 视窗: %APPDATA%\Claude\claude_desktop_config.json
    • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

  2. 添加服务器配置:

    {
  "mcpServers": {
    "notes": {
      "command": "node",
      "args": ["/absolute/path/to/notes-mcp-server/build/index.js"]
    }
  }
}

    重要：替换 /absolute/path/to/notes-mcp-server 使用项目目录的实际绝对路径。

    示例：

    • 视窗: "args": ["C:\\Users\\YourName\\projects\\notes-mcp-server\\build\\index.js"]
    • macOS/Linux: "args": ["/home/username/projects/notes-mcp-server/build/index.js"]

  3. 重新启动克劳德桌面

📖 可用工具

连接到Claude Desktop后，这些工具将可用：

create_note

  • 描述：创建一个带有标题和内容的新笔记
  • 参数:
    • title （string，必填）：注释的标题
    • content （string）：注释的内容/正文

read_note

  • 描述：按标题阅读现有注释的内容
  • 参数:
    • title （string，必填）：要阅读的注释的标题

update_note

  • 描述：更新现有注释的内容
  • 参数:
    • title （string，必填）：要更新的注释的标题
    • content （string）：注释的新内容

list_notes

  • 描述：获取所有可用笔记的列表
  • 参数：无

delete_note

  • 描述：删除现有注释
  • 参数:
    • title （string，必填）：要删除的注释的标题

💡 使用示例

连接到Claude Desktop后，您可以使用自然语言：

  • 创建一个标题为“购物清单”的注释，内容为“牛奶、鸡蛋、面包”
  • “显示我的购物清单备注”
  • “更新我的购物清单，添加‘黄油、奶酪’”
  • “我有什么笔记？”
  • “删除我的旧购物清单备注”

🗂️ 数据存储

注释作为单独的JSON文件存储在 data/ 具有此结构的目录：

{
  "title": "Shopping List",
  "content": "Milk, Eggs, Bread",
  "created": "2025-01-20T10:30:00.000Z",
  "updated": "2025-01-20T10:30:00.000Z"
}

文件名由笔记标题生成：

  • 转换为小写
  • 用连字符替换空格
  • 删除特殊字符
  • 添加 .json 扩展

示例：“我的购物清单！”→ my-shopping-list.json

🔧 发展

可用脚本

  • npm run build：将TypeScript编译为JavaScript
  • npm run start：构建并运行服务器
  • npm run dev：快速开发构建和运行

项目配置

  • TypeScript：为ES2022配置了Node16模块
  • 输出：编译为 build/ 目录
  • 类型检查：启用严格模式以更好地捕获错误
  • 模块：具有适当Node.js兼容性的ES模块

🐛 故障排除

服务器未出现在Claude Desktop中

  1. 检查路径是否正确 claude_desktop_config.json 绝对正确
  2. 验证服务器构建没有错误(npm run build)
  3. 完全重新启动克劳德桌面
  4. 检查Claude Desktop日志是否有错误

工具不工作

  1. 确保 data/ 目录可写
  2. 检查TypeScript编译错误
  3. 验证是否已安装所有依赖项

常见问题

  • 路径问题：在Claude Desktop配置中始终使用绝对路径
  • 权限问题：确保 data/ 目录具有写入权限
  • TypeScript错误：运行 npm run build 检查编译问题

📄 许可证

此项目根据MIT许可证获得许可-请参阅 许可证 文件以获取详细信息。

🤝 贡献

欢迎投稿！请随时提交拉取请求。对于重大更改，请先打开一个问题来讨论您想要更改的内容。

  1. 分叉存储库
  2. 创建功能分支(git checkout -b feature/AmazingFeature)
  3. 提交您的更改(git commit -m 'Add some AmazingFeature')
  4. 推到分支(git push origin feature/AmazingFeature)
  5. 打开拉取请求

🎓 学习笔记

该项目展示了几个重要的MCP概念：

  1. MCP服务器结构：如何使用工具设置基本的MCP服务器
  2. 数据验证：使用Zod进行输入验证和类型安全
  3. 文件操作：使用Node.js文件系统的持久存储
  4. 错误处理：优雅的错误处理和用户反馈
  5. TypeScript集成：具有现代JavaScript功能的类型安全开发

📚 资源

🤝 贡献

这是一个学习项目，但请随时：

  • 提出改进建议
  • 报告错误
  • 添加功能
  • 分享您自己的MCP服务器实验

快乐编码和学习！ 🚀

相关 MCP