AI导哈

模型上下文协议服务器

一个基于Go语言的生产级Model Context Protocol服务器，通过JSON-RPC 2.0 stdio传输暴露文件系统工具和笔记资源。

  • by devaloi
  • Go
  • 本地部署
  • 1 星标
  • 更新于
在 GitHub 查看 devaloi/mcpserve

使用说明

麦克普塞尔

A生产质量 模型上下文协议 Go中的（MCP）服务器——通过JSON-RPC 2.0 stdio传输公开文件系统工具和注释资源。

什么是MCP？

模型上下文协议是一个开放标准，允许像克劳德这样的人工智能助手通过结构化的JSON-RPC 2.0接口与外部工具和数据源进行交互。MCP服务器暴露 工具 （AI可以调用的操作）和 资源 （人工智能可以读取的数据），实现对本地系统的安全、沙盒访问。

特性

  • 8个内置工具 --文件I/O、目录列表、搜索和markdown注释管理
  • 资源提供程序 --使用URI寻址将文件和笔记作为可读资源提供
  • 基于stdio的JSON-RPC 2.0 --标准MCP传输；与任何合规的客户合作
  • 路径沙盒 --所有文件操作都限制在可配置的根目录中
  • JSON模式验证 --工具输入在执行前根据模式进行验证
  • 零外部依赖 --只有Go标准库
  • 平滑关闭 --处理SIGINT/SIGTERM以实现干净进程终止
  • 可通过环境配置 --根目录、notes目录和日志级别

建筑

┌─────────────────────────────────────────────────┐
│                  Claude / AI Client              │
└──────────────────────┬──────────────────────────┘
                       │ JSON-RPC 2.0 (stdin/stdout)
┌──────────────────────▼──────────────────────────┐
│                 StdioTransport                   │
│          (newline-delimited JSON)                │
└──────────────────────┬──────────────────────────┘
                       │
┌──────────────────────▼──────────────────────────┐
│                   Server                         │
│         (method dispatch + protocol)             │
├─────────────────┬───────────────────────────────┤
│   ToolRegistry  │      ResourceProvider          │
├────────┬────────┼──────────┬────────────────────┤
│  File  │ Notes  │   File   │      Notes         │
│ Tools  │ Tools  │ Provider │     Provider        │
└────────┴────────┴──────────┴────────────────────┘
         │                    │
    ┌────▼────┐          ┌───▼────┐
    │  Root   │          │ Notes  │
    │  Dir    │          │  Dir   │
    └─────────┘          └────────┘

快速开始

# Clone and build
git clone https://github.com/devaloi/mcpserve.git
cd mcpserve
make build

# Run with defaults (current directory as root)
./bin/mcpserve

# Run with custom configuration
MCPSERVE_ROOT_DIR=~/projects \
MCPSERVE_NOTES_DIR=~/notes \
MCPSERVE_LOG_LEVEL=debug \
./bin/mcpserve

使用Claude Desktop

添加到您的 claude_desktop_config.json:

{
  "mcpServers": {
    "mcpserve": {
      "command": "/path/to/mcpserve",
      "env": {
        "MCPSERVE_ROOT_DIR": "/Users/you/projects",
        "MCPSERVE_NOTES_DIR": "/Users/you/notes"
      }
    }
  }
}

在macOS上，此文件位于 ~/Library/Application Support/Claude/claude_desktop_config.json.

工具

工具 说明 必需参数
read_file 读取文件内容（最大1MB） path
write_file 将内容写入文件，根据需要创建目录 path, content
list_directory 列出目录中的条目 path （可选： recursive)
search_files 搜索与glob模式匹配的文件 path, pattern
create_note 使用YAML frontmatter创建标记注释 title, content （可选： tags)
read_note 按标题阅读笔记 title
list_notes 列出注释，可选择按标签筛选 （可选： tag)
search_notes 按标题和内容中的子字符串搜索笔记 query

资源

URI模式 描述 MIME类型
file:///{path} 根目录下的文件 按扩展名自动检测
notes:///{slug} 由slug编写的Markdown注释 text/markdown

配置

环境变量 默认值 描述
MCPSERVE_ROOT_DIR . （当前目录） 文件工具和文件资源的根目录
MCPSERVE_NOTES_DIR $ROOT_DIR/notes 钞票存储目录
MCPSERVE_LOG_LEVEL info 日志详细程度

发展

先决条件： 转到1.22+

make build          # Build binary to bin/mcpserve
make test           # Run tests with race detection
make lint           # Run golangci-lint
make cover          # Generate coverage report
make clean          # Remove build artifacts

项目结构

mcpserve/
├── cmd/mcpserve/           # Entry point — config, wiring, signal handling
│   └── main.go
├── internal/
│   ├── protocol/           # JSON-RPC 2.0 types and encoding
│   │   ├── types.go
│   │   └── jsonrpc.go
│   ├── transport/          # Transport interface and stdio implementation
│   │   ├── transport.go
│   │   └── stdio.go
│   ├── server/             # MCP server core — dispatch, handlers
│   │   ├── server.go
│   │   ├── handler.go
│   │   └── integration_test.go
│   ├── tools/              # Tool registry and built-in tools
│   │   ├── registry.go
│   │   ├── filesystem.go
│   │   └── notes.go
│   ├── resources/          # Resource providers
│   │   ├── provider.go
│   │   ├── fileprovider.go
│   │   ├── notesprovider.go
│   │   └── composite.go
│   └── schema/             # JSON Schema validation (Draft 7 subset)
│       └── validator.go
├── testdata/               # Test fixtures
├── docs/                   # Documentation and specs
├── Makefile
├── go.mod
└── LICENSE

设计决策

  • 零外部依赖 --整个服务器，包括JSON模式验证，都是用Go标准库实现的。这最大限度地降低了供应链风险，并使二元关系保持较小。
  • 手动滚动JSON模式验证器 --支持MCP工具模式（类型、必需、属性、枚举、最小/最大约束）所需的Draft 7子集，而无需引入完整的模式库。
  • 接口驱动架构 — ToolRegistry, ResourceProvider，以及 Transport 都是接口，使每一层都可以独立测试和替换。
  • 复合资源提供者 --多个URI方案（文件：///，注释：///）是通过组合提供者来处理的，而不是构建一个单一的资源处理程序。
  • 路径沙盒 --所有文件系统访问都会解析根目录的路径，并拒绝遍历尝试，从而防止AI访问沙盒外的文件。
  • 日志记录标准 --stdout专门为JSON-RPC 2.0协议流保留；所有诊断输出都会进入stderr。

许可证

麻省理工学院——见 许可证 了解详情。

相关 MCP