weave-mcp

maximilien/weave-mcp

3.3

If you are the rightful owner of weave-mcp and would like to certify it and/or have it hosted online, please leave a comment on the right or send an email to dayong@mcphub.com.

The Weave MCP Server is a Model Context Protocol server designed for vector database operations, providing seamless integration with the weave-cli tool.

Tools
9
Resources
0
Prompts
0

Weave MCP Server

A Model Context Protocol (MCP) server for vector database operations, built with Go and designed to work seamlessly with the weave-cli tool.

Recent Updates (v0.4.0): Major upgrade to weave-cli v0.8.2 adds support for 6 new vector databases (Qdrant, Neo4j, Pinecone, OpenSearch, Elasticsearch, enhanced Supabase), bringing total to 11 databases. New features include operation-specific timeouts (20-300s based on operation type and deployment), VDB-specific error messages for better debugging, enhanced test coverage (36.6%), and comprehensive timeout system for reliable operations across all databases.

Features

  • Dual Transport Support: HTTP/HTTPS and stdio MCP transports
  • HTTPS/TLS Support: Optional HTTPS with auto-redirect from HTTP ()
  • Vector Database Support: 11 databases supported - Weaviate, Supabase, MongoDB, Milvus, Chroma, Qdrant, Neo4j, Pinecone, OpenSearch, Elasticsearch, and Mock
  • MCP Tools: Complete set of tools for collection and document management
  • MCP Inspector: Web-based debugging and testing interface
  • Configuration: YAML + Environment Variables
  • Testing: Comprehensive unit and integration tests with mocks
  • Scripts: Build, start, stop, lint, and test automation
  • Embedding Support: OpenAI and custom local embeddings
  • Logging: Comprehensive file logging with monitoring tools
  • Code Reuse: Direct integration with weave-cli for consistency

Transport Modes

The Weave MCP Server supports two transport modes:

HTTP/HTTPS Transport

  • Binary: bin/weave-mcp
  • URL: http://localhost:8030 or https://localhost:8030 (with TLS enabled)
  • Use Case: Web applications, API integrations, testing
  • Features: RESTful API endpoints, health checks, easy debugging, optional TLS/HTTPS
  • HTTPS Setup: See

stdio Transport

  • Binary: bin/weave-mcp-stdio
  • Transport: stdin/stdout communication
  • Use Case: MCP clients like Claude Desktop, direct integration
  • Features: Native MCP protocol, efficient communication, client integration

MCP Tools

The server exposes 23 MCP tools for comprehensive vector database operations:

Collection Management (7 tools)

  • list_collections - List all collections in the vector database
  • create_collection - Create a new collection with specified schema
  • delete_collection - Delete a collection and all its documents
  • count_collections - Count total number of collections
  • show_collection - Show detailed collection info (schema, count, properties)
  • get_collection_stats - Get collection statistics (document count, schema info)

Document Management (11 tools)

  • list_documents - List documents in a collection with pagination
  • create_document - Create a new document in a collection
  • batch_create_documents - Create multiple documents in a single batch operation
  • get_document - Retrieve a specific document by ID
  • update_document - Update a document's content or metadata
  • delete_document - Delete a document from a collection
  • count_documents - Count documents in a collection
  • show_document_by_name - Show a document by its filename
  • delete_document_by_name - Delete a document by its filename
  • delete_all_documents - Delete all documents from a collection or all collections

Query Operations (2 tools)

  • query_documents - Perform semantic search on documents
  • execute_query - Execute semantic search across one or all collections

AI-Powered Tools (2 tools)

  • suggest_schema - Analyze documents and suggest optimal collection schema using AI
  • suggest_chunking - Analyze documents and suggest optimal chunking configuration using AI

Health & Monitoring (1 tool)

  • health_check - Check database connectivity and health status

Embedding Management (2 tools)

  • list_embedding_models - List all available embedding models and their properties
  • show_collection_embeddings - Show embedding configuration for a specific collection

For detailed documentation of each tool, see .

MCP Inspector

The MCP Inspector is a web-based debugging tool that provides a graphical interface for testing and exploring MCP tools. It's particularly useful for:

  • Testing MCP Tools: Execute tools with custom parameters
  • Debugging: See detailed request/response information
  • Exploration: Discover available tools and their schemas
  • Development: Rapid prototyping and testing

Inspector Features

  • Interactive Tool Testing: Execute any MCP tool with custom parameters
  • Real-time Logging: See tool execution logs in real-time
  • Schema Exploration: Browse available tools and their schemas
  • Request/Response Inspection: Detailed view of MCP protocol messages
  • Web Interface: Easy-to-use browser-based interface

Access

Once started, the MCP Inspector is typically available at:

Inspector Configuration

The inspector uses the official npx @modelcontextprotocol/inspector method and is configured to connect to the Weave MCP Server using the configuration in tools/mcp-inspector-config.json. This file is created during setup and includes:

  • Server connection details
  • Environment variable mapping
  • Tool configuration

Quick Start

Prerequisites

  • Go 1.21 or later
  • Vector database (Weaviate, Milvus, or use mock for testing)

Installation

  1. Clone the repository:
git clone https://github.com/maximilien/weave-mcp.git
cd weave-mcp
  1. Run the setup script (installs MCP Inspector and builds servers):
./setup.sh
  1. Configure the server:
cp config.yaml.example config.yaml
cp .env.example .env
# Edit config.yaml and .env with your settings

Manual Installation (if setup script fails):

# Install Go dependencies
go mod tidy

# Build servers
./build.sh

MCP Inspector Setup (Optional)

The MCP Inspector provides a web-based interface for testing and debugging MCP tools. To set it up:

# Install MCP Inspector and dependencies
./setup.sh

This will:

  • Install Node.js dependencies (if not already installed)
  • Clone the MCP Inspector repository
  • Install inspector dependencies
  • Create inspector configuration
  • Build the MCP server

Prerequisites for MCP Inspector:

  • Node.js 22.7.5+ (required for MCP Inspector)
  • npm (comes with Node.js)

Note: MCP Inspector requires Node.js 22.7.5 or later. If you have an older version, the setup script will skip the inspector installation but continue with the server setup.

Building

# Build both HTTP and stdio servers
./build.sh

# Build only HTTP server
./build.sh http

# Build only stdio server
./build.sh stdio

This will:

  • Download Go dependencies
  • Run tests
  • Build the MCP server binaries (HTTP and/or stdio)
  • Create build information

Running

Start HTTP Server
# Start HTTP server in foreground
./start.sh http

# Start HTTP server as daemon
./start.sh http --daemon
Start stdio Server
# Show stdio server configuration for MCP clients
./start.sh stdio
Start MCP Inspector
# Start inspector (will start HTTP server if not running)
./start.sh inspector

# Or start both HTTP server and inspector together
./start.sh both
Stop Services
# Stop HTTP server
./stop.sh http

# Stop stdio server (if running)
./stop.sh stdio

# Stop inspector
./stop.sh inspector

# Stop all services
./stop.sh all

# Check status
./stop.sh status
MCP Client Integration

For stdio server integration with MCP clients like Cursor 2.0, Claude Desktop, and other MCP-compatible clients:

# Show stdio server configuration
./start.sh stdio

For Cursor 2.0:

Add this configuration to your Cursor MCP settings (typically in ~/.cursor/mcp.json or via Cursor Settings):

{
  "mcpServers": {
    "weave-mcp": {
      "command": "/path/to/weave-mcp/bin/weave-mcp-stdio",
      "args": []
    }
  }
}

For Claude Desktop:

Add this configuration to your Claude Desktop MCP settings:

{
  "mcpServers": {
    "weave-mcp": {
      "command": "/path/to/weave-mcp/bin/weave-mcp-stdio",
      "args": []
    }
  }
}

Note: The server is now compatible with Cursor 2.0's enhanced MCP interface and uses MCP SDK v1.1.0 for optimal compatibility.

Monitor logs
# Monitor all logs
./tools/tail-logs.sh

# Monitor HTTP server logs only
./tools/tail-logs.sh mcp

# Monitor stdio server logs only
./tools/tail-logs.sh stdio

# Monitor MCP Inspector logs only
./tools/tail-logs.sh inspector

Testing

Run all tests:

./test.sh

Run specific test types:

./test.sh unit        # Unit tests only
./test.sh integration # Integration tests only
./test.sh fast        # Fast tests (unit + mock integration)
./test.sh coverage    # Tests with coverage report

Linting

Check code quality:

./lint.sh

Configuration

Environment Variables

Create a .env file with the following variables:

# Vector Database Configuration
VECTOR_DB_TYPE=weaviate-cloud

# Weaviate Cloud Configuration
WEAVIATE_URL=https://your-cluster-url.weaviate.network
WEAVIATE_API_KEY=your-weaviate-api-key
OPENAI_API_KEY=your-openai-api-key

# Collection Names
WEAVIATE_COLLECTION=WeaveDocs
WEAVIATE_COLLECTION_IMAGES=WeaveImages

# MCP Server Configuration
MCP_SERVER_HOST=localhost
MCP_SERVER_PORT=8030

Configuration File

The config.yaml file supports multiple database configurations:

databases:
  default: weaviate-cloud
  vector_databases:
    - name: weaviate-cloud
      type: weaviate-cloud
      url: ${WEAVIATE_URL}
      api_key: ${WEAVIATE_API_KEY}
      openai_api_key: ${OPENAI_API_KEY}
      collections:
        - name: WeaveDocs
          type: text
          description: Main text documents collection
        - name: WeaveImages
          type: image
          description: Image documents collection
    - name: mock
      type: mock
      enabled: true
      simulate_embeddings: true
      embedding_dimension: 384
      collections:
        - name: WeaveDocs
          type: text
          description: Mock text documents collection

API Endpoints

The MCP server exposes the following HTTP endpoints:

  • GET /health - Health check (includes database status)
  • GET /mcp/tools/list - List available MCP tools
  • POST /mcp/tools/call - Execute an MCP tool

Example API Usage

Health check
curl http://localhost:8030/health

Returns:

{
  "status": "healthy",
  "timestamp": "2025-11-14T19:22:26Z",
  "database": {
    "status": "healthy",
    "type": "weaviate-cloud",
    "name": "weaviate-cloud"
  }
}

Returns HTTP 503 if database is unhealthy.

List available tools
curl http://localhost:8030/mcp/tools/list
Execute a tool
curl -X POST http://localhost:8030/mcp/tools/call \
  -H "Content-Type: application/json" \
  -d '{
    "name": "list_collections",
    "arguments": {}
  }'
Create a collection
curl -X POST http://localhost:8030/mcp/tools/call \
  -H "Content-Type: application/json" \
  -d '{
    "name": "create_collection",
    "arguments": {
      "name": "MyCollection",
      "type": "text",
      "description": "My test collection"
    }
  }'
Create a document
curl -X POST http://localhost:8030/mcp/tools/call \
  -H "Content-Type: application/json" \
  -d '{
    "name": "create_document",
    "arguments": {
      "collection": "MyCollection",
      "url": "https://example.com/doc1",
      "text": "This is a test document",
      "metadata": {
        "type": "test",
        "author": "user"
      }
    }
  }'
Update a document
curl -X POST http://localhost:8030/mcp/tools/call \
  -H "Content-Type: application/json" \
  -d '{
    "name": "update_document",
    "arguments": {
      "collection": "MyCollection",
      "document_id": "document-id-123",
      "content": "Updated document content",
      "metadata": {
        "updated_by": "user",
        "last_modified": "2025-01-09"
      }
    }
  }'
Query documents
curl -X POST http://localhost:8030/mcp/tools/call \
  -H "Content-Type: application/json" \
  -d '{
    "name": "query_documents",
    "arguments": {
      "collection": "MyCollection",
      "query": "test document",
      "limit": 5
    }
  }'

Logging and Monitoring

The Weave MCP Server includes comprehensive logging and monitoring capabilities.

Log Files

  • Location: ./logs/weave-mcp.log
  • Format: Structured JSON with timestamps and caller information
  • Output: Both console and file logging simultaneously
  • Auto-creation: Logs directory is created automatically on startup

Log Monitoring Tools

Use the ./tools/tail-logs.sh script to monitor logs in real-time:

Monitor all logs
./tools/tail-logs.sh all
Monitor MCP server logs only
./tools/tail-logs.sh mcp
Check service status
./tools/tail-logs.sh status
Show recent logs
./tools/tail-logs.sh recent
Show help
./tools/tail-logs.sh help

Log Features

  • Real-time monitoring: Tail logs as they're written
  • Service status: Check if MCP server is running
  • Color-coded output: Easy to read with syntax highlighting
  • System integration: Includes system logs for comprehensive monitoring
  • Multiple modes: Different monitoring options for different needs

Example Log Output

{
  "level": "info",
  "ts": 1759848440.371797,
  "caller": "src/main.go:87",
  "msg": "Starting Weave MCP Server",
  "address": "localhost:8030",
  "version": "0.0.6",
  "git_commit": "da2f207"
}
{
  "level": "info",
  "ts": 1759848441.123456,
  "caller": "src/main.go:95",
  "msg": "MCP server started successfully"
}
{
  "level": "info",
  "ts": 1759848442.789012,
  "caller": "src/pkg/mcp/handlers.go:45",
  "msg": "Tool called",
  "tool": "list_collections",
  "collection": "WeaveDocs"
}

Development

Project Structure

weave-mcp/
├── src/
│   ├── main.go                 # HTTP server entry point
│   ├── cmd/
│   │   └── stdio/
│   │       └── main.go         # stdio server entry point
│   └── pkg/
│       ├── config/            # Configuration management
│       ├── mcp/               # MCP server implementation
│       ├── weaviate/          # Weaviate client (from weave-cli)
│       ├── milvus/            # Milvus client
│       ├── mock/              # Mock client for testing
│       └── version/           # Version information
├── tests/                     # Test files
├── tools/                     # Utility scripts
│   ├── tail-logs.sh          # Log monitoring script
│   └── mcp-inspector-config.json # MCP Inspector configuration
├── logs/                      # Log files directory
│   └── .gitkeep              # Preserve directory in git
├── schemas/                   # Collection schemas
├── bin/                       # Built binaries
│   ├── weave-mcp             # HTTP server binary
│   └── weave-mcp-stdio       # stdio server binary
├── config.yaml               # Configuration file
├── .env                      # Environment variables
├── setup.sh                  # Setup script (MCP Inspector + build)
├── build.sh                  # Build script
├── start.sh                  # Start script
├── stop.sh                   # Stop script
├── test.sh                   # Test script
└── lint.sh                   # Lint script

Adding New Tools

To add a new MCP tool:

  1. Add the tool definition in src/pkg/mcp/server.go:
s.registerTool(Tool{
    Name:        "my_new_tool",
    Description: "Description of my new tool",
    InputSchema: map[string]interface{}{
        "type": "object",
        "properties": map[string]interface{}{
            "param1": map[string]interface{}{
                "type":        "string",
                "description": "Parameter description",
            },
        },
        "required": []string{"param1"},
    },
    Handler: s.handleMyNewTool,
})
  1. Implement the handler in src/pkg/mcp/handlers.go:
func (s *Server) handleMyNewTool(ctx context.Context, 
    args map[string]interface{}) (interface{}, error) {
    // Implementation here
    return result, nil
}
  1. Add tests in tests/mcp_test.go

Adding New Vector Database Support

To add support for a new vector database:

  1. Create a new client package in src/pkg/
  2. Implement the database interface
  3. Update the MCP server to support the new database type
  4. Add configuration support
  5. Add tests

Contributing

  1. Fork the repository
  2. Create a feature branch
  3. Make your changes
  4. Add tests for new functionality
  5. Run the test suite: ./test.sh
  6. Run the linter: ./lint.sh
  7. Submit a pull request

License

This project is licensed under the MIT License - see the file for details.

Related Projects

Support

For issues and questions:

  1. Check the Issues page
  2. Create a new issue with detailed information
  3. Include logs and configuration details

Documentation

  • - Complete version history and release notes
  • - Common issues and solutions
  • GitHub Releases - Download releases