feat: add OpenViking control plane MCP server + CLI#408
Merged
cuericlee merged 6 commits intoJun 21, 2026
Conversation
Add a new package that exposes the OpenViking control plane (topapi · top cluster) collection-management Actions as both an MCP server and a Typer CLI, sharing one core (client.py) so each Action is available from both front-ends. - 6 core Actions: list / create / get / delete / usage / api-key (GetOpenVikingCollectionUserAccess) - Pluggable auth (common/auth.py): dev-phase ManualHeadersAuth replays headers supplied manually (e.g. copied from the browser); AuthProvider leaves room for a future AK/SK signer or dedicated API key without touching client/tool/cli. - MCP server defaults to stdio (uvx-launchable); create/delete are exposed with confirm-first guidance in their tool descriptions. - Lazy config from VIKING_HOST / VIKING_HEADERS_FILE|VIKING_HEADERS / VIKING_SCHEMA / OPENVIKING_PROJECT; headers file accepts JSON or raw 'Key: Value' blocks.
…d live
Switch the request model to the console proxy the browser actually uses, and
verify the read-only Actions against the live staging console.
- Endpoint: POST {schema}://{host}/api/top/{service}/{region}/{api_version}/{Action}
with Action/Version in the path (no query params); body is the Action params.
- Extract host/region/service/api_version into config (VIKING_HOST default
console.volcengine.com, VIKING_REGION=cn-beijing, VIKING_API_SERVICE=vikingdb,
VIKING_API_VERSION=2025-06-09) and expose them as CLI flags + ControlPlaneConfig.action_path().
- Correct the api-key Action: the doc's GetOpenVikingCollectionUserAccess does
not exist on the console; use AccessOpenVikingApiKey (returns the default user's
plaintext {UserID, Role, ApiKey}). ListOpenVikingUser only returns a masked key.
- Live-verified read-only: list / get / usage / api-key. create/delete unchanged
(not exercised live as they are billable).
- READMEs updated for the console endpoint, new env vars, and verified Action names.
…-plane endpoint The control-plane TopAPI is now compiled into the OpenViking data-plane cluster and authenticated with an Ark AgentPlan ApiKey. Replace the dev-phase console-proxy approach accordingly: - auth: drop ManualHeadersAuth (browser cookie/JWT replay); add BearerTokenAuth that sends Authorization: Bearer <key> (the backend only accepts Bearer, not X-API-Key). - endpoint: single base URL config (VIKING_ENDPOINT / --endpoint), default https://api.vikingdb.cn-beijing.volces.com/openviking (reserved public gateway, not live yet); action path is /api/openviking/{Action}, no query. - config: slim to api_key/endpoint/project; drop headers/region/service/ api_version and all header-blob parsing. - client: fix api-key action name AccessOpenVikingApiKey -> GetOpenVikingCollectionUserAccess (the former 404s on the data cluster); emit the new multi-credential create format (VLM/Embedding carry a Credentials[] list; source moves into each credential); for source=agentplan the model ApiKey falls back to the configured key and model names default. - cli: replace --host/--schema/--region/--service/--api-version/--headers-file /--header with --endpoint/-e and --api-key/-k. - docs: rewrite README/README_zh for Bearer-only auth and the new endpoint. Verified against the staging data-plane pod via port-forward: list returns 200, missing auth returns 401, create reaches the backend (blocked only by the account-side AgentPlan order gate, ProductUnordered). End-to-end create/provisioning + data-plane key verification still pending an account with AgentPlan deduction enabled.
…N_API_KEY The key is an Ark AgentPlan ApiKey; name the env var accordingly. VIKING_API_KEY -> AGENTPLAN_API_KEY across config, CLI help, and docs. VIKING_ENDPOINT / OPENVIKING_PROJECT are unchanged (not AgentPlan-specific).
…keep default endpoint - Add skills/openviking-controlplane/SKILL.md documenting the ov-cp workflow (config, commands, agentplan create defaults, cold-start chain, data-plane key usage) and link it from the READMEs. - Show env-var-based CLI usage (export AGENTPLAN_API_KEY, then no per-command flag). - Stop customizing VIKING_ENDPOINT in the primary examples / .mcp.json — use the default endpoint and document overriding it (for port-forward testing) only as a note.
AgentFileNum is not meaningful for control-plane usage; strip it in the shared client.get_usage so both the CLI and MCP tool omit it. Update the tool docstring accordingly.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Adds
mcp-server-openviking-controlplane— an MCP server and anov-cpCLI for the OpenViking control plane (topapi), for managing OV collections (libraries). Both front-ends share one core (client.py), so each capability is available from MCP and the CLI alike.Capabilities (6 core Actions)
ListOpenVikingCollectionslist_collectionsov-cp listCreateOpenVikingCollectioncreate_collectionov-cp createGetOpenVikingCollectionget_collectionov-cp get <rid>DeleteOpenVikingCollectiondelete_collectionov-cp delete <rid>GetOpenVikingUsageget_usageov-cp usage <rid>GetOpenVikingCollectionUserAccessget_collection_api_keyov-cp api-key <rid>Auth & endpoint
Authorization: Bearer <key>(the control plane accepts only Bearer, notX-API-Key); auth is pluggable viacommon/auth.py.{endpoint}/api/openviking/{Action}; default basehttps://api.vikingdb.cn-beijing.volces.com/openviking, overridable withVIKING_ENDPOINT/--endpoint.AGENTPLAN_API_KEY,VIKING_ENDPOINT,OPENVIKING_PROJECT) or CLI flags; lazy so--helpworks without configuration.Transport
uvx/.mcp.jsonsubprocess style);--transport sseis also supported.Verification
initialize→list_tools(6) →call_tool), including the structured error path.create→ poll untilREADY→api-key; the returned data-plane key then drives the library data plane (/health,/api/v1/system/status,/api/v1/fs/ls).Notes
skills/openviking-controlplane/SKILL.md.kubectl port-forwardto the data cluster; the branch is a few commits behindmainand can be rebased before merge.