Recutils MCP

Recutils MCP服务器（Go版本）

在Go中实现的高性能数据库MCP（模型上下文协议）工具，提供类型安全操作。

关于Recutils

GNU 资源 是一个轻量级的基于文本的数据库工具包，将结构化数据存储在纯文本文件中。主要特征包括：

• 人类可读 -数据以纯文本格式存储，易于阅读和编辑
• 打字记录 -支持多种记录类型，类似于关系数据库中的表
• 强大的查询功能 -提供类似SQL的查询语言(recsel)
• 无服务器 -无需数据库服务器进程，零依赖关系
• VCS友好 -文本格式自然支持Git和其他版本控制工具

✨ 特性

• ✅ 高性能 -编译语言，启动速度提高2倍，内存使用量减少50%
• ✅ 类型安全 -编译时检查，减少运行时错误
• ✅ 简单部署 -单个二进制文件（~7.3MB），不需要运行时环境
• ✅ 并发支持 -goroutine提供了更好的并发性能
• ✅ 完整的功能 -支持查询、插入、更新、删除和获取数据库信息
• ✅ MCP协议 -符合模型上下文协议标准

🚀 快速开始

系统要求

• 转到1.21+（用于开发）
• recutils工具包（用于运行时）

# Install recutils
# Ubuntu/Debian
sudo apt-get install recutils

# macOS
brew install recutils

安装

选项1：使用go install（推荐）

# Install directly to GOBIN
go install github.com/nixihz/recutils-mcp@latest

# The binary will be installed to $GOBIN (default: ~/go/bin)
# Add to PATH if needed:
export PATH=$PATH:$(go env GOBIN)

# Run the server
recutils-mcp

选项2：从源代码构建

# 1. Clone the repository
git clone https://github.com/nixihz/recutils-mcp.git
cd recutils-mcp

# 2. Install dependencies
go mod download

# 3. Run tests
make test

# 4. Build project
make build

# 5. Run server
./recutils-mcp

🔧 与Claude Desktop集成

将以下配置添加到Claude Desktop的配置文件中：

{
  "mcpServers": {
    "recutils": {
      "command": "$(go env GOBIN)/recutils-mcp",
      "args": []
    }
  }
}

注： 替换 $(go env GOBIN)/recutils-mcp 如果您将其安装在其他位置，请使用实际路径。在macOS/Linux上使用 go install，默认路径为 ~/go/bin/recutils-mcp.

📋 可用命令

make all           # Run tests and build
make test          # Run all tests
make test-cover    # Run tests with coverage
make build         # Build binary
make clean         # Clean build files
make fmt           # Format code
make vet           # Static check
make bench         # Benchmark test
make security      # Security check
make help          # Show help

🔧 MCP工具列表

📖 使用示例

创建数据库并插入数据

# 1. Start server
./recutils-mcp

# 2. Call tools via MCP client (Example JSON)

# Query records
{
  "method": "tools/call",
  "params": {
    "name": "recutils_query",
    "arguments": {
      "database_file": "example.rec",
      "query_expression": "Name = 'John Doe'"
    }
  }
}

# Insert records
{
  "method": "tools/call",
  "params": {
    "name": "recutils_insert",
    "arguments": {
      "database_file": "example.rec",
      "record_type": "Person",
      "fields": {
        "Name": "John Doe",
        "Age": 25,
        "City": "New York"
      }
    }
  }
}

Direct Go API使用

package main

import (
    "context"
    "fmt"
    "github.com/nixihz/recutils-mcp/recutils"
)

func main() {
    ctx := context.Background()
    op := recutils.NewRecordOperation()

    // Insert record
    result, err := op.InsertRecord(ctx, "test.rec", "Person", map[string]interface{}{
        "Name": "John Doe",
        "Age":  25,
    })
    if err != nil {
        fmt.Printf("Error: %v\n", err)
        return
    }
    fmt.Printf("Insert successful: %+v\n", result)

    // Query records
    queryResult, err := op.QueryRecords(ctx, "test.rec", "", "")
    if err != nil {
        fmt.Printf("Error: %v\n", err)
        return
    }
    fmt.Printf("Query result: %+v\n", queryResult)
}

📁 项目结构

recutils-mcp/
├── go.mod                    # Go module definition
├── main.go                   # Main entry point
├── README.md                 # Project documentation (this file)
├── Makefile                  # Build script
├── build.sh                  # Build script
├── .gitignore                # Git ignore file
├── recutils/
│   └── operations.go        # recutils operations encapsulation
└── server/
    ├── mcp_server.go        # MCP server implementation
    └── mcp_server_test.go   # Test code

🔍 正确的文件格式

recutils数据库文件必须遵循特定格式：

%rec: Person

Name: John Doe
Age: 25
City: New York

Name: Jane Smith
Age: 30

格式要求：

• %rec: 后面必须有一个空行
• 字段格式： field_name: value
• 记录必须用空行分隔
• 重要提示： 记录必须以换行符结尾（固定）

🧪 测试

# Run all tests
go test ./... -v

# Run specific test
go test -run TestMCPServer -v

# Test coverage
go test ./... -cover

# Benchmark test
go test -bench=. ./...

测试结果

=== RUN   TestMCPServer
--- PASS: TestMCPServer (0.04s)
    ✓ QueryRecords
    ✓ GetDatabaseInfo
    ✓ InsertRecord
    ✓ VerifyInsert

=== RUN   TestMCPServerIntegration
--- PASS: TestMCPServerIntegration (0.05s)
    ✓ FullWorkflow

PASS

🐛 故障排除

1.服务器无法启动

检查是否安装了转盘：

recsel --version

2.许可问题

确保数据库文件具有读/写权限：

chmod 644 database.rec

3.文件格式错误

使用 recsel 要验证文件格式，请执行以下操作：

recsel your_database.rec

📚 更多资源

• 回避官方文件
• MCP协议规范
• Go语言文档

🤝 贡献

欢迎投稿！请阅读CONTRIBUTING.md了解详情。

📄 许可证

MIT许可证

🏷️ 版本历史记录

• v1.0.0 -首次发布

- Go语言重构 - 完全支持MCP协议 - 修复了数据库文件格式问题 - 性能提高2倍

______________________________________________________________________

推荐用于生产！ 🚀