# OpenViking MCP Server

MCP Server for integrating [OpenViking](https://github.com/volcengine/OpenViking) context database with Cloudwise SA Workflow Skills.

## Features

- **Semantic Search**: Query knowledge base with natural language
- **Product Catalog**: Access Cloudwise product information (APM, DOEM, CMDB, etc.)
- **Solution Templates**: Retrieve industry-specific solutions
- **Hierarchical Context**: L0/L1/L2 tiered loading for optimal token usage
- **Mock Mode**: Test without real OpenViking server or API keys

## Quick Start

### Installation

```bash
cd openviking-mcp
pip install -e ".[dev]"
```

### Mock Mode (No API Key Required)

```bash
# Run in mock mode for testing
export OPENVIKING_MOCK_MODE=true
python -m openviking_mcp.server
```

### Real Mode (Requires OpenViking Server)

```bash
# Start OpenViking server first
openviking-server --port 1933

# Then run MCP server
export OPENVIKING_URL=http://localhost:1933
python -m openviking_mcp.server
```

## Configuration

Environment variables:

| Variable | Default | Description |
|----------|---------|-------------|
| `OPENVIKING_URL` | `http://localhost:1933` | OpenViking HTTP API URL |
| `OPENVIKING_STORE` | `cloudwise-kb` | Default store name |
| `OPENVIKING_TIER_DEFAULT` | `L1` | Default context tier (L0/L1/L2) |
| `OPENVIKING_MOCK_MODE` | `false` | Enable mock mode for testing |
| `OPENVIKING_HTTP_TIMEOUT` | `30` | HTTP request timeout |

## Claude Desktop Configuration

Add to `~/.claude/mcp-servers/openviking-mcp.json`:

```json
{
  "name": "openviking-mcp",
  "transport": "stdio",
  "command": "python",
  "args": ["-m", "openviking_mcp.server"],
  "env": {
    "OPENVIKING_URL": "http://localhost:1933",
    "OPENVIKING_STORE": "cloudwise-kb",
    "OPENVIKING_MOCK_MODE": "false"
  }
}
```

## Available Tools

| Tool | Description |
|------|-------------|
| `query_kb` | Semantic search across knowledge base |
| `get_product` | Get Cloudwise product details |
| `get_solution` | Retrieve solution templates |
| `list_directory` | Browse KB directory structure |
| `get_context_tier` | Get L0/L1/L2 context levels |

## Development

```bash
# Run tests
pytest tests/ -v

# Run with coverage
pytest tests/ --cov=openviking_mcp

# Run mock mode demo
python scripts/demo_mock.py

# Lint
ruff check src/
mypy src/
```

## Mock Mode

Mock mode provides simulated responses for development and testing without requiring:
- OpenViking server running
- Embedding API keys
- Actual knowledge base data

Enable mock mode:
```bash
export OPENVIKING_MOCK_MODE=true
```

## Architecture

```
22 SA Skills → MCP Client → MCP Server → HTTP Client → OpenViking API → KB
                                ↓
                           Mock Mode (可选)
```

## License

MIT