使用说明

⚠️ 存档存储库

该项目已不再维护，并于2026年4月存档。

不接受任何新功能或错误修复。

Maestro MCP服务器

模型上下文协议（MCP）服务器的本地Golang实现大师和大师知识。此服务器提供矢量数据库操作通过标准化的MCP接口，支持Milvus和Weaviate矢量数据库。

特性

矢量数据库支持：Milvus与Weaviate的整合
MCP协议：完整的模型上下文协议实现
嵌入支持：OpenAI和自定义本地嵌入服务
模拟数据库：用于测试和开发的内置模拟
综合测试：单元测试、集成测试和端到端测试
生产就绪：优雅的关机、健康检查和日志记录
配置：YAML和环境变量支持

快速开始

先决条件

转到1.21或更高版本
Git

安装

克隆仓库:

git clone https://github.com/maximilien/maestro-mcp.git
cd maestro-mcp

设置环境:

cp .env.example .env
# Edit .env with your configuration

构建服务器:
```
./build.sh
```
运行测试:
```
./test.sh
```
启动服务器:
```
./start.sh
```

服务器将于启动 http://localhost:8030 默认情况下。

配置

环境变量

服务器使用环境变量 MAESTRO_MCP_ 前缀。钥匙配置选项：

# Server Configuration
MAESTRO_MCP_SERVER_HOST=localhost
MAESTRO_MCP_SERVER_PORT=8030

# Vector Database Configuration
MAESTRO_MCP_VECTOR_DB_TYPE=milvus  # or weaviate

# Milvus Configuration
MAESTRO_MCP_VECTOR_DB_MILVUS_HOST=localhost
MAESTRO_MCP_VECTOR_DB_MILVUS_PORT=19530

# Weaviate Configuration
MAESTRO_MCP_VECTOR_DB_WEAVIATE_URL=http://localhost:8080
MAESTRO_MCP_VECTOR_DB_WEAVIATE_API_KEY=your_api_key

# Embedding Configuration
MAESTRO_MCP_EMBEDDING_PROVIDER=openai
MAESTRO_MCP_EMBEDDING_MODEL=text-embedding-ada-002
MAESTRO_MCP_EMBEDDING_API_KEY=your_openai_api_key

# Logging Configuration
MAESTRO_MCP_LOGGING_LEVEL=info
MAESTRO_MCP_LOGGING_FORMAT=json

配置文件

您还可以使用 config.yaml 文件：

version: "0.0.1"

server:
  host: "localhost"
  port: 8030

mcp:
  tool_timeout: "15s"
  vector_db:
    type: "milvus"
    milvus:
      host: "localhost"
      port: 19530
  embedding:
    provider: "openai"
    model: "text-embedding-ada-002"

可用工具

MCP服务器提供以下工具：

数据库管理

create_vector_database：创建新的矢量数据库实例
list_databases：列出所有可用的矢量数据库实例
setup_database：建立矢量数据库并创建集合
cleanup：清理资源和密切联系

文档操作

write_document：将单个文档写入矢量数据库
write_documents：将多个文档写入矢量数据库
list_documents：列出矢量数据库中的文档
count_documents：获取收藏中的文档数量
delete_document：按ID删除单个文档
delete_documents：按ID删除多个文档

查询操作

query：使用自然语言查询文档
search：执行向量相似性搜索

收集管理

list_collections：列出矢量数据库中的所有集合
get_collection_info：获取收藏信息
create_collection：创建新收藏
delete_collection：删除收藏

使用示例

使用curl

列出可用工具:

curl http://localhost:8030/mcp/tools/list

创建矢量数据库:

curl -X POST http://localhost:8030/mcp/tools/call \
  -H "Content-Type: application/json" \
  -d '{
    "name": "create_vector_database",
    "arguments": {
      "db_name": "my_db",
      "db_type": "milvus",
      "collection_name": "documents"
    }
  }'

撰写文档:

curl -X POST http://localhost:8030/mcp/tools/call \
  -H "Content-Type: application/json" \
  -d '{
    "name": "write_document",
    "arguments": {
      "db_name": "my_db",
      "url": "https://example.com/doc1",
      "text": "This is a test document about machine learning.",
      "metadata": {
        "author": "John Doe",
        "category": "AI"
      }
    }
  }'

查询文档:

curl -X POST http://localhost:8030/mcp/tools/call \
  -H "Content-Type: application/json" \
  -d '{
    "name": "query",
    "arguments": {
      "db_name": "my_db",
      "query": "What is machine learning?",
      "limit": 5
    }
  }'

使用MCP客户端

添加到MCP客户端配置中：

{
  "mcpServers": {
    "maestro-mcp": {
      "command": "./bin/maestro-mcp",
      "args": [],
      "env": {
        "MAESTRO_MCP_SERVER_HOST": "localhost",
        "MAESTRO_MCP_SERVER_PORT": "8030"
      }
    }
  }
}

发展

项目结构

maestro-mcp/
├── src/                    # Source code
│   ├── main.go            # Main entry point
│   └── pkg/               # Packages
│       ├── config/        # Configuration management
│       ├── mcp/           # MCP server implementation
│       ├── server/         # HTTP server
│       └── vectordb/       # Vector database implementations
├── tests/                 # Test files
├── .github/               # GitHub Actions workflows
│   └── workflows/
│       ├── ci.yml         # Continuous Integration
│       └── release.yml    # Release automation
├── config.yaml           # Configuration file
├── .env.example          # Environment variables example
├── CHANGELOG.md          # Changelog
├── build.sh              # Build script
├── test.sh               # Test script
├── start.sh              # Start script
├── stop.sh               # Stop script
├── lint.sh               # Linting script
└── e2e.sh                # End-to-end test script

建筑

# Build the server
./build.sh

# Build with clean
./build.sh clean

测试

# Run unit tests
./test.sh unit

# Run integration tests
./test.sh integration

# Run all tests
./test.sh all

# Run tests with coverage
./test.sh coverage

代码检查

# Run linter
./lint.sh

# Skip security checks
./lint.sh --skip-security

端到端测试

# Run full E2E test suite
./e2e.sh

CI/CD

该项目使用GitHub Actions进行持续集成和部署。

持续集成

CI管道在每个推送和拉取请求上运行，包括：

代码检查：使用golangci lint、gofmt和shellcheck进行代码质量检查
建筑：多平台编译（Linux、macOS、Windows）
测试：单元测试、集成测试和端到端测试
安全：使用gosec和govulncheck进行漏洞扫描
矩阵测试：使用多个Go版本进行跨平台测试

发布自动化

发布工作流自动执行：

触发器：在git标签上（例如。， v1.0.0)或人工调度
测试：在发布之前运行完整的测试套件
构建：为多个平台创建二进制文件
包裹：生成校验和和和发行说明
出版：创建带有可下载资产的GitHub版本

工作流文件

.github/workflows/ci.yml：主CI管道
.github/workflows/release.yml：发布自动化

身份徽章

服务器管理

# Start server
./start.sh

# Start in daemon mode
./start.sh --daemon

# Start with build
./start.sh --build

# Check server status
./stop.sh status

# Stop server
./stop.sh

# Restart server
./stop.sh restart

矢量数据库支持

米尔维斯

Milvus是一个矢量数据库，专为可扩展的相似性搜索和人工智能而设计应用。

配置:

MAESTRO_MCP_VECTOR_DB_TYPE=milvus
MAESTRO_MCP_VECTOR_DB_MILVUS_HOST=localhost
MAESTRO_MCP_VECTOR_DB_MILVUS_PORT=19530
MAESTRO_MCP_VECTOR_DB_MILVUS_USERNAME=root
MAESTRO_MCP_VECTOR_DB_MILVUS_PASSWORD=password

Weaviate

Weaviate是一个开源的矢量数据库，允许您存储数据对象以及向量嵌入。

配置:

MAESTRO_MCP_VECTOR_DB_TYPE=weaviate
MAESTRO_MCP_VECTOR_DB_WEAVIATE_URL=http://localhost:8080
MAESTRO_MCP_VECTOR_DB_WEAVIATE_API_KEY=your_api_key

模拟数据库

为了测试和开发，服务器包括一个模拟向量数据库模拟所有操作，不需要外部依赖。

嵌入支持

OpenAI嵌入

MAESTRO_MCP_EMBEDDING_PROVIDER=openai
MAESTRO_MCP_EMBEDDING_MODEL=text-embedding-ada-002
MAESTRO_MCP_EMBEDDING_API_KEY=your_openai_api_key

自定义本地嵌入

MAESTRO_MCP_EMBEDDING_PROVIDER=custom_local
MAESTRO_MCP_EMBEDDING_URL=http://localhost:8000/embed
MAESTRO_MCP_EMBEDDING_MODEL=nomic-embed-text
MAESTRO_MCP_EMBEDDING_VECTOR_SIZE=768
MAESTRO_MCP_EMBEDDING_API_KEY=your_custom_api_key

API终点

健康检查

GET /health

返回服务器运行状况和活动矢量数据库。

列出工具

GET /mcp/tools/list

返回所有可用的MCP工具及其模式。

呼叫工具

POST /mcp/tools/call
Content-Type: application/json

{
  "name": "tool_name",
  "arguments": {
    "param1": "value1",
    "param2": "value2"
  }
}

使用提供的参数执行MCP工具。

错误处理

服务器提供全面的错误处理：

验证错误：参数无效或缺少必需参数
数据库错误：连接失败、查询错误等。
超时错误：超出配置超时的操作
资源错误：内存、磁盘或网络问题

所有错误均以一致的JSON格式返回：

{
  "error": "Error message describing what went wrong"
}

日志记录

服务器使用具有可配置级别的结构化JSON日志记录：

debug：详细的调试信息
info：关于运营的一般信息
warn：非关键问题的警告信息
error：失败的错误消息

日志输出可以配置为stdout、stderr或文件。

演出

该服务器专为高性能而设计：

并发操作：可以管理多个矢量数据库同时
连接池：高效的数据库连接管理
超时保护：所有操作都有可配置的超时
内存效率高：通过适当的清理实现最小的内存占用

安全

安全功能包括：

输入验证：所有输入在处理前都经过验证
SQL注入保护：参数化查询和输入净化
速率限制：API端点的可配置速率限制
认证：支持API密钥和自定义身份验证

发布

下载

从下载最新版本发布页面.

支持的平台

Linux：amd64、arm64
macOS：amd64、arm64（苹果硅）
视窗：amd64

二进制安装

下载适合您平台的二进制文件
使其可执行： chmod +x maestro-mcp-*
运行： ./maestro-mcp-*

验证

使用每个文件中提供的校验和验证下载的完整性释放：

sha256sum -c checksums.txt

贡献

分叉存储库
创建要素分支
进行更改
添加新功能的测试
运行测试套件： ./test.sh all
运行门楣： ./lint.sh
确保CI通过
提交拉取请求

许可证

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

支持

有关支持和问题：

在GitHub上创建问题
检查文档
查看测试示例

更新日志

v0.0.3

Milvus官方客户集成
官方Weaviate客户端集成
更新了客户端初始化配置
更新安装方法以使用官方客户端模式

v0.0.2

v0.0.1

初始版本
Milvus和Weaviate支撑
用于测试的模拟数据库
全面的测试套件
MCP协议实现
配置管理
生产就绪功能