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: The server now supports both HTTP and stdio transports, includes an MCP Inspector for debugging and testing, comprehensive logging and monitoring capabilities, direct integration with weave-cli for code reuse, a complete CI/CD pipeline with automated testing and releases, document update functionality for flexible document management workflows, and full compatibility with Cursor 2.0's enhanced MCP interface.

Features

Dual Transport Support: HTTP and stdio MCP transports
Vector Database Support: Weaviate, Milvus, and Mock databases
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 Transport

Binary: bin/weave-mcp
URL: http://localhost:8030
Use Case: Web applications, API integrations, testing
Features: RESTful API endpoints, health checks, easy debugging

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 the following MCP tools:

Collection Management

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

Document Management

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

Query Operations

query_documents - Perform semantic search on documents

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:

Web Interface: http://localhost:6274 (with auth token)
MCP Server: http://localhost:8030

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

Clone the repository:

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

Run the setup script (installs MCP Inspector and builds servers):

./setup.sh

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:

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,
})

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
}

Add tests in tests/mcp_test.go

Adding New Vector Database Support

To add support for a new vector database:

Create a new client package in src/pkg/
Implement the database interface
Update the MCP server to support the new database type
Add configuration support
Add tests

Contributing

Fork the repository
Create a feature branch
Make your changes
Add tests for new functionality
Run the test suite: ./test.sh
Run the linter: ./lint.sh
Submit a pull request

License

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

Related Projects

weave-cli - Command-line tool for vector database operations
Model Context Protocol - MCP specification and SDKs

Support

For issues and questions:

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

Documentation

Changelog - Complete version history and release notes
Troubleshooting Guide - Common issues and solutions
GitHub Releases - Download releases

Name		Name	Last commit message	Last commit date
Latest commit History 60 Commits
.github/workflows		.github/workflows
docs		docs
logs		logs
schemas		schemas
src		src
tests		tests
tools		tools
.env.example		.env.example
.gitignore		.gitignore
.yamllint		.yamllint
CHANGELOG.md		CHANGELOG.md
LICENSE		LICENSE
README.md		README.md
build.sh		build.sh
config.yaml		config.yaml
config.yaml.example		config.yaml.example
go.mod		go.mod
go.sum		go.sum
lint.sh		lint.sh
setup.sh		setup.sh
start.sh		start.sh
stop.sh		stop.sh
test.sh		test.sh
weave-mcp-stdio.log		weave-mcp-stdio.log

License

maximilien/weave-mcp

Folders and files

Latest commit

History

Repository files navigation

Weave MCP Server

Features

Transport Modes

HTTP Transport

stdio Transport

MCP Tools

Collection Management

Document Management

Query Operations

MCP Inspector

Inspector Features

Access

Inspector Configuration

Quick Start

Prerequisites

Installation

MCP Inspector Setup (Optional)

Building

Running

Start HTTP Server

Start stdio Server

Start MCP Inspector

Stop Services

MCP Client Integration

Monitor logs

Testing

Linting

Configuration

Environment Variables

Configuration File

API Endpoints

Example API Usage

Health check

List available tools

Execute a tool

Create a collection

Create a document

Update a document

Query documents

Logging and Monitoring

Log Files

Log Monitoring Tools

Monitor all logs

Monitor MCP server logs only

Check service status

Show recent logs

Show help

Log Features

Example Log Output

Development

Project Structure

Adding New Tools

Adding New Vector Database Support

Contributing

License

Related Projects

Support

Documentation

About

Topics

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases 16

Packages 0

Contributors 2

Uh oh!

Languages

Packages