Skip to content

Self-evolving Context Database for AI Agents. Unify Agent Memory, Knowledge RAG and Skills.

Add OpenClaw skill for OpenViking MCP integration (#114)

Zayn Jarvis4f50e771c83c
diff --git a/examples/mcp-query/README.md b/examples/mcp-query/README.md
index 645fefa69..f66e4da6d 100644
--- a/examples/mcp-query/README.md
+++ b/examples/mcp-query/README.md
@@ -20,17 +20,17 @@ cp ov.conf.example ov.conf
# Install dependencies
uv sync
-# Start the server (streamable HTTP on port 8000)
+# Start the server (streamable HTTP on port 2033)
uv run server.py
```
-The server will be available at `http://127.0.0.1:8000/mcp`.
+The server will be available at `http://127.0.0.1:2033/mcp`.
## Connect from Claude
```bash
# Add as MCP server in Claude CLI
-claude mcp add --transport http openviking http://localhost:8000/mcp
+claude mcp add --transport http openviking http://localhost:2033/mcp
```
Or add to `.mcp.json`:
@@ -40,7 +40,7 @@ Or add to `.mcp.json`:
"mcpServers": {
"openviking": {
"type": "http",
- "url": "http://localhost:8000/mcp"
+ "url": "http://localhost:2033/mcp"
}
}
}
@@ -54,7 +54,7 @@ uv run server.py [OPTIONS]
--config PATH Config file path (default: ./ov.conf, env: OV_CONFIG)
--data PATH Data directory path (default: ./data, env: OV_DATA)
--host HOST Bind address (default: 127.0.0.1)
- --port PORT Listen port (default: 8000, env: OV_PORT)
+ --port PORT Listen port (default: 2033, env: OV_PORT)
--transport TYPE streamable-http | stdio (default: streamable-http)
```
@@ -62,5 +62,5 @@ uv run server.py [OPTIONS]
```bash
npx @modelcontextprotocol/inspector
-# Connect to http://localhost:8000/mcp
+# Connect to http://localhost:2033/mcp
```
diff --git a/examples/mcp-query/server.py b/examples/mcp-query/server.py
index 5de9d2caf..562eefab1 100644
--- a/examples/mcp-query/server.py
+++ b/examples/mcp-query/server.py
@@ -9,7 +9,7 @@ Provides MCP tools for:
Usage:
uv run server.py
- uv run server.py --config ./ov.conf --data ./data --port 8000
+ uv run server.py --config ./ov.conf --data ./data --port 2033
"""
import argparse
@@ -46,7 +46,7 @@ def _get_recipe() -> Recipe:
return _recipe
-def create_server(host: str = "127.0.0.1", port: int = 8000) -> FastMCP:
+def create_server(host: str = "127.0.0.1", port: int = 2033) -> FastMCP:
"""Create and configure the MCP server."""
mcp = FastMCP(
name="openviking-mcp",
@@ -240,12 +240,12 @@ Examples:
uv run server.py --transport stdio
# Connect from Claude CLI
- claude mcp add --transport http openviking http://localhost:8000/mcp
+ claude mcp add --transport http openviking http://localhost:2033/mcp
Environment variables:
OV_CONFIG Path to config file (default: ./ov.conf)
OV_DATA Path to data directory (default: ./data)
- OV_PORT Server port (default: 8000)
+ OV_PORT Server port (default: 2033)
OV_DEBUG Enable debug logging (set to 1)
""",
)
@@ -270,8 +270,8 @@ Environment variables:
parser.add_argument(
"--port",
type=int,
- default=int(os.getenv("OV_PORT", "8000")),
- help="Port to listen on (default: 8000)",
+ default=int(os.getenv("OV_PORT", "2033")),
+ help="Port to listen on (default: 2033)",
)
parser.add_argument(
"--transport",
diff --git a/examples/openclaw-skill/SKILL.md b/examples/openclaw-skill/SKILL.md
new file mode 100644
index 000000000..d39e7ac8d
--- /dev/null
+++ b/examples/openclaw-skill/SKILL.md
@@ -0,0 +1,111 @@
+---
+name: openviking
+description: RAG and semantic search via OpenViking Context Database MCP server. Query documents, search knowledge base, add files/URLs to vector memory. Use for document Q&A, knowledge management, AI agent memory, file search, semantic retrieval. Triggers on "openviking", "search documents", "semantic search", "knowledge base", "vector database", "RAG", "query pdf", "document query", "add resource".
+---
+
+# OpenViking - Context Database for AI Agents
+
+OpenViking is ByteDance's open-source **Context Database** designed for AI Agents — a next-generation RAG system that replaces flat vector storage with a filesystem paradigm for managing memories, resources, and skills.
+
+**Key Features:**
+- **Filesystem paradigm**: Organize context like files with URIs (`viking://resources/...`)
+- **Tiered context (L0/L1/L2)**: Abstract → Overview → Full content, loaded on demand
+- **Directory recursive retrieval**: Better accuracy than flat vector search
+- **MCP server included**: Full RAG pipeline via Model Context Protocol
+
+---
+
+## Quick Check: Is It Set Up?
+
+```bash
+test -f ~/code/openviking/examples/mcp-query/ov.conf && echo "Ready" || echo "Needs setup"
+curl -s http://localhost:8000/mcp && echo "Running" || echo "Not running"
+```
+
+## If Not Set Up → Initialize
+
+Run the init script (one-time):
+
+```bash
+bash ~/.openclaw/skills/openviking-mcp/scripts/init.sh
+```
+
+This will:
+1. Clone OpenViking from `https://github.com/volcengine/OpenViking`
+2. Install dependencies with `uv sync`
+3. Create `ov.conf` template
+4. **Pause for you to add API keys** (embedding.dense.api_key, vlm.api_key)
+
+**Required: Volcengine/Ark API Keys**
+
+| Config Key | Purpose |
+|------------|---------|
+| `embedding.dense.api_key` | Semantic search embeddings |
+| `vlm.api_key` | LLM for answer generation |
+
+Get keys from: https://console.volcengine.com/ark
+
+## Start the Server
+
+```bash
+cd ~/code/openviking/examples/mcp-query
+uv run server.py
+```
+
+Options:
+- `--port 8000` - Listen port
+- `--host 127.0.0.1` - Bind address
+- `--data ./data` - Data directory
+
+Server will be at: `http://127.0.0.1:8000/mcp`
+
+## Connect to Claude
+
+```bash
+claude mcp add --transport http openviking http://localhost:8000/mcp
+```
+
+Or add to `~/.mcp.json`:
+```json
+{
+ "mcpServers": {
+ "openviking": {
+ "type": "http",
+ "url": "http://localhost:8000/mcp"
+ }
+ }
+}
+```
+
+## Tools Available
+
+| Tool | Description |
+|------|-------------|
+| `query` | Full RAG pipeline — search + LLM answer |
+| `search` | Semantic search only, returns docs |
+| `add_resource` | Add files, directories, or URLs |
+
+## Example Usage
+
+Once connected via MCP:
+
+```
+"Query: What is OpenViking?"
+"Search: machine learning papers"
+"Add https://example.com/article to knowledge base"
+"Add ~/documents/report.pdf"
+```
+
+## Troubleshooting
+
+| Issue | Fix |
+|-------|-----|
+| Port in use | `uv run server.py --port 9000` |
+| Auth errors | Check API keys in ov.conf |
+| Server not found | Ensure it's running: `curl localhost:8000/mcp` |
+
+## Files
+
+- `ov.conf` - Configuration (API keys, models)
+- `data/` - Vector database storage
+- `server.py` - MCP server implementation
diff --git a/examples/openclaw-skill/scripts/init.sh b/examples/openclaw-skill/scripts/init.sh
new file mode 100644
index 000000000..8d55dff85
--- /dev/null
+++ b/examples/openclaw-skill/scripts/init.sh
@@ -0,0 +1,57 @@
+#!/bin/bash
+# OpenViking MCP Server Setup - One-time setup
+
+set -e
+
+REPO_URL="${OPENVIKING_REPO:-https://github.com/volcengine/OpenViking.git}"
+INSTALL_DIR="${OPENVIKING_DIR:-$HOME/code/openviking}"
+
+echo "=== OpenViking MCP Server Setup ==="
+
+# Check prerequisites
+if ! command -v uv &> /dev/null; then
+ echo "❌ uv not found. Install with: curl -LsSf https://astral.sh/uv/install.sh | sh"
+ exit 1
+fi
+
+# Clone if not exists
+if [ -d "$INSTALL_DIR" ]; then
+ echo "✓ OpenViking already cloned at $INSTALL_DIR"
+else
+ echo "→ Cloning OpenViking to $INSTALL_DIR..."
+ git clone "$REPO_URL" "$INSTALL_DIR"
+fi
+
+cd "$INSTALL_DIR/examples/mcp-query"
+
+# Install dependencies
+echo "→ Installing dependencies..."
+uv sync
+
+# Create config if not exists
+if [ -f "ov.conf" ]; then
+ echo "✓ Config already exists (ov.conf)"
+else
+ echo "→ Creating config template..."
+ cp ov.conf.example ov.conf
+ echo ""
+ echo "⚠️ ACTION REQUIRED: Edit ov.conf and add your API keys:"
+ echo " embedding.dense.api_key - Volcengine/Ark API key for embeddings"
+ echo " vlm.api_key - Volcengine/Ark API key for LLM"
+ echo ""
+ echo " File location: $INSTALL_DIR/examples/mcp-query/ov.conf"
+ echo ""
+ read -p "Press Enter after you've configured ov.conf..."
+fi
+
+echo ""
+echo "=== Setup Complete ==="
+echo "Start server: cd $INSTALL_DIR/examples/mcp-query && uv run server.py"
+echo ""
+echo "Tools available:"
+echo " - query: Full RAG pipeline (search + LLM answer)"
+echo " - search: Semantic search only"
+echo " - add_resource: Add files/URLs to knowledge base"
+echo ""
+echo "Connect to Claude:"
+echo " claude mcp add --transport http openviking http://localhost:8000/mcp"