AI导哈

Recutils数据库MCP工具

高性能的Recutils数据库MCP（模型上下文协议）工具，提供类型安全操作，适用于轻量级文本数据库管理和查询。

  • by nixihz
  • Go
  • 本地部署
  • 更新于
在 GitHub 查看 nixihz/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工具列表

工具名称 描述 参数
recutils_query 查询记录 数据库文件、查询表达式（可选）、输出格式（可选）
recutils_insert 插入记录 数据库文件、记录类型、字段
recutils_update 更新记录 数据库文件、查询表达式、字段
recutils_delete 删除记录 数据库文件，查询表达式
recutils_info 获取数据库信息 database_file

📖 使用示例

创建数据库并插入数据

# 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

📚 更多资源

🤝 贡献

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

📄 许可证

MIT许可证

🏷️ 版本历史记录

  • v1.0.0 -首次发布
    • Go语言重构
    • 完全支持MCP协议
    • 修复了数据库文件格式问题
    • 性能提高2倍

推荐用于生产！ 🚀

相关 MCP