🚀 基于 Go 的 MCP 服务端（notes-server）

这是一个符合 JSON-RPC 2.0 标准的服务器，以示例形式实现了模型上下文协议 (MCP) 的笔记管理功能。您可以对其进行修改，并将其作为样板代码应用到自己的项目中。该服务端支持跨平台开发，包含开发和发布构建配置、命令行界面和服务组件。

✨ 主要特性

• 采用 JSON-RPC 2.0 标准接口
• 支持跨平台（Windows、Linux、macOS）
• 具备线程安全的笔记管理功能
• 包含开发和发布构建配置
• 拥有服务和命令行界面组件

📦 安装指南

先决条件

• 需要安装 Go 1.21 或更高版本
• 需使用 GNU Make 或兼容的构建工具
• 要安装 Git（用于获取版本信息）

构建命令

开发构建（包含调试符号和竞态检测）

# 构建所有组件的所有平台
make dev

# 为特定平台构建
make dev-windows
make dev-linux
make dev-darwin

# 构建特定组件
make build-cmd
make build-service

发布构建（优化且去除符号）

# 构建所有组件的所有平台
make release-all

# 为特定平台构建
make release-windows
make release-linux
make release-darwin

本地运行

# 运行命令行界面
make run-cmd

# 运行服务
make run-service

查看所有目标选项

make help

构建输出

二进制文件将创建在 bin 目录中：

• 开发构建：bin/dev/
• 发布构建：bin/release/

💻 使用示例

组件模块

命令行界面 (cmd)

命令行界面可让您直接访问服务器功能。

服务 (service)

服务组件能够实现系统级集成和后台运行功能。

资源管理

服务器实现了一个笔记存储系统，具体包括：

• 自定义 note:// URI 方案，用于访问单个笔记
• 资源元数据（名称、描述、MIME 类型）
• 线程安全的并发访问

提示功能

可用提示命令：

• summarize-notes：创建所有存储笔记的摘要
  • 可选参数：style（"简洁"/"详细"）
  • 根据风格偏好结合所有当前笔记
  • 线程安全的笔记访问

工具功能

可用工具命令：

• add-note：向服务器添加新的笔记
  • 必要参数：name（字符串）、content（字符串）
  • 线程安全的状态更新
  • 返回确认消息

配置指南

用于 Claude Desktop 的配置

要通过命令行界面配置，请执行以下命令：

# 设置 MCP 地址
export MCP_ADDR="http://localhost:8080"

# 设置 MCP 认证令牌
export MCP_TOKEN="your_token_here"

开发指南

项目结构

项目的文件夹结构如下所示：

notes-server/
├── cmd/
│   ├── main.go         # 命令行入口
│   └── service.go      # 服务实现
├── internal/
│   ├── handlers/       # 请求处理逻辑
│   └── models/         # 数据模型定义
└── go.mod              # 模块依赖管理文件

调试与日志

要启用调试模式，请在运行时设置环境变量：

# 启用调试模式
export DEBUG=true

默认情况下，服务会在标准错误流中输出日志。

📚 详细文档

错误码定义

以下是 MCP 服务返回的错误代码：

注意事项

⚠️ 重要提示

• 在生产环境中，请确保设置适当的防火墙和安全策略。
• 使用环境变量管理敏感信息，避免直接硬编码。
• 定期备份数据以防止意外丢失。