# OpenViking MCP Plugin for Grok CLI

Connect [Grok CLI](https://docs.x.ai/) / Grok Build to an [OpenViking](https://github.com/volcengine/OpenViking) context database.

The plugin ships a **stdio → HTTP MCP proxy** that:

- Starts as a local MCP server inside Grok
- Forwards JSON-RPC to your OpenViking server’s `/mcp` endpoint
- Reads credentials from `~/.openviking/ovcli.conf` or `OPENVIKING_*` env vars  
  (no API key pasted into `~/.grok/config.toml`)

You get the full OpenViking tool surface: `health`, `find`, `search`, `recall`, `remember`, `list`, `read`, `glob`, `grep`, code tools, `add_resource`, and more.

## Requirements

- [Grok CLI](https://x.ai/cli) installed and logged in (`grok login`)
- [Node.js](https://nodejs.org/) **18+**
- A reachable OpenViking server (local or hosted)

## Quick install

```bash
bash <(curl -fsSL https://raw.githubusercontent.com/shpaw415/openviking-grok-plugin/main/install.sh)
```

The installer will:

1. Write or update `~/.openviking/ovcli.conf` (URL + API key)
2. Run `grok plugin install … --trust`
3. Enable the plugin

### Non-interactive

```bash
bash <(curl -fsSL https://raw.githubusercontent.com/shpaw415/openviking-grok-plugin/main/install.sh) \
  --url 'https://your-openviking.example.com' \
  --api-key 'YOUR_KEY' \
  --yes
```

Local unauthenticated server:

```bash
./install.sh --url 'http://127.0.0.1:1933' --api-key '' --yes --local
```

### Install without the script

```bash
# 1. Credentials
mkdir -p ~/.openviking
cat > ~/.openviking/ovcli.conf <<'EOF'
{
  "url": "https://your-openviking.example.com",
  "api_key": "YOUR_KEY"
}
EOF
chmod 600 ~/.openviking/ovcli.conf

# 2. Plugin
grok plugin install shpaw415/openviking-grok-plugin --trust
grok plugin enable openviking
```

Or from a checkout:

```bash
git clone https://github.com/shpaw415/openviking-grok-plugin.git
cd openviking-grok-plugin
./install.sh --local --yes
```

### MCP-only (absolute path, no plugin manager)

Useful if you prefer `config.toml` registration:

```bash
./install.sh --local --mcp-only --yes
# → grok mcp add openviking -- node /path/to/servers/mcp-proxy.mjs
```

## Verify

```bash
grok mcp doctor openviking
# In a session:
#   /ov          → status report
#   /mcps        → openviking ready
```

Ask Grok:

> Use the openviking MCP: run health, then list `viking://resources`.

## What you get

| Component | Path | Purpose |
|-----------|------|---------|
| MCP proxy | `servers/mcp-proxy.mjs` | stdio bridge to OpenViking `/mcp` |
| Status | `/ov` command | Health, identity, toggles |
| Skill | `skills/openviking` | When/how to use the tools |
| Rule | `rules/openviking.md` | Prefer recall over guessing |

## Configuration

Priority (highest → lowest):

1. Environment: `OPENVIKING_URL` / `OPENVIKING_BASE_URL`, `OPENVIKING_API_KEY` / `OPENVIKING_BEARER_TOKEN`, `OPENVIKING_ACCOUNT`, `OPENVIKING_USER`
2. `~/.openviking/ovcli.conf` (or `OPENVIKING_CLI_CONFIG_FILE`)
3. `~/.openviking/ov.conf` (legacy server config)
4. Default `http://127.0.0.1:1933`

Example `ovcli.conf`:

```json
{
  "url": "https://openviking.example.com",
  "api_key": "…",
  "account": "optional-team",
  "user": "optional-user"
}
```

Optional:

| Variable | Effect |
|----------|--------|
| `OPENVIKING_DEBUG=1` | Proxy + plugin debug logs under `~/.openviking/logs/` |
| `OPENVIKING_PEER_ID` | Stable peer id for multi-workspace isolation |
| `OPENVIKING_WORKSPACE_PEER=0` | Disable workspace-derived peer |

**Do not** put the bearer token in `[mcp_servers.openviking.headers]` if you use this plugin — the proxy already authenticates. If you previously added a raw HTTP MCP entry in `config.toml`, remove or disable it to avoid two servers with the same tools:

```bash
grok mcp remove openviking   # only if it was the old HTTP entry
# reinstall via this plugin afterward
```

## Uninstall

```bash
bash <(curl -fsSL https://raw.githubusercontent.com/shpaw415/openviking-grok-plugin/main/install.sh) --uninstall
# or
grok plugin uninstall openviking --confirm
```

`ovcli.conf` is kept so other harnesses (Claude Code, Cursor, …) keep working.

## Development

```bash
git clone https://github.com/shpaw415/openviking-grok-plugin.git
cd openviking-grok-plugin
grok plugin validate .
./install.sh --local --yes
```

Proxy smoke test (credentials required):

```bash
# Initialize handshake over stdio (partial)
printf '%s\n' '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"smoke","version":"0"}}}' \
  | node servers/mcp-proxy.mjs
```

## Relationship to upstream OpenViking

The stdio proxy core is adapted from the official [OpenViking memory plugins](https://github.com/volcengine/OpenViking/tree/main/examples) (`examples/memory-plugin-shared`, `examples/claude-code-memory-plugin`), licensed Apache-2.0. This repository packages a **Grok CLI–first** distribution with an installer and Grok plugin manifest (`.grok-plugin/plugin.json`).

Upstream also ships Claude Code, Codex, Cursor, and other harness plugins. Use those installers for non-Grok agents:

```bash
bash <(curl -fsSL https://raw.githubusercontent.com/volcengine/OpenViking/main/examples/memory-plugin-shared/install.sh)
```

## License

Apache-2.0 — see [LICENSE](./LICENSE).

## Links

- [OpenViking](https://github.com/volcengine/OpenViking)
- [OpenViking docs](https://docs.openviking.ai/)
- [Grok plugins guide](https://docs.x.ai/) (Plugins / MCP)