@vantageos/vantage-registry-mcp 1.1.0

package/README.md

@@ -0,0 +1,239 @@
+# @vantageos/vantage-registry-mcp
+
+MCP server exposing [VantageRegistry](https://github.com/elpiarthera/vantage-registry) Convex functions as Claude Code tools via stdio transport.
+
+**Version:** 1.1.0
+**Backend:** Convex (vibrant-ibex-858)
+**Transport:** stdio (Claude Code MCP protocol)
+
+---
+
+## Installation
+
+Add to your Claude Code MCP config (`.claude/mcp.json` or equivalent):
+
+```json
+{
+  "mcpServers": {
+    "vantage-registry": {
+      "command": "bunx",
+      "args": ["@vantageos/vantage-registry-mcp"],
+      "env": {
+        "CONVEX_URL": "https://vibrant-ibex-858.convex.site"
+      }
+    }
+  }
+}
+```
+
+Or set `CONVEX_URL` in `.env.local` at the repo root.
+
+---
+
+## Tools
+
+### Teams
+
+| Tool | Description |
+|------|-------------|
+| `upsert_team` | Create or update a team (upsert by name) |
+| `list_teams` | List all teams — optional `status` filter |
+| `get_team` | Get a team by Convex document ID |
+
+### Agents
+
+| Tool | Description |
+|------|-------------|
+| `upsert_agent` | Create or update an agent (upsert by name) |
+| `list_agents` | List agents — optional `status` / `team` filters |
+| `list_agents_by_team` | List agents for a specific team |
+| `get_agent` | Get an agent by Convex document ID |
+
+### Skills
+
+| Tool | Description |
+|------|-------------|
+| `upsert_skill` | Create or update a skill (upsert by name) |
+| `list_skills` | List skills — optional `status` / `team` / `category` filters |
+| `list_skills_by_team` | List skills for a specific team |
+| `list_skills_by_category` | List skills for a specific category |
+| `get_skill` | Get a skill by Convex document ID |
+
+### Plugins
+
+| Tool | Description |
+|------|-------------|
+| `upsert_plugin` | Create or update a plugin (upsert by name) |
+| `list_plugins` | List plugins — optional `status` filter |
+| `get_plugin` | Get a plugin by Convex document ID |
+
+### Hooks
+
+| Tool | Description |
+|------|-------------|
+| `upsert_hook` | Create or update a hook (upsert by name) |
+| `list_hooks` | List hooks — optional `status` / `event` / `scope` filters |
+| `get_hook` | Get a hook by Convex document ID |
+
+### Prompts
+
+| Tool | Description |
+|------|-------------|
+| `upsert_prompt` | Create or update a prompt (upsert by name) |
+| `list_prompts` | List prompts — optional `status` / `team` filters |
+| `get_prompt` | Get a prompt by Convex document ID |
+
+### Templates
+
+| Tool | Description |
+|------|-------------|
+| `upsert_template` | Create or update a template (upsert by name) |
+| `list_templates` | List templates — optional `team` and `template_type` filters |
+| `get_template` | Get a template by Convex document ID |
+
+**New in 1.1.0:** `list_templates` accepts a `template_type` filter:
+```
+template_type: "mission" | "document" | "checklist"
+```
+
+Example: list only checklist templates for the core team:
+```
+list_templates(team="core", template_type="checklist")
+```
+
+### Runbooks
+
+**New in 1.1.0.** Runbooks are structured, versioned operational playbooks stored in VantageRegistry.
+
+| Tool | Description |
+|------|-------------|
+| `upsert_runbook` | Create or update a runbook (upsert by name) |
+| `get_runbook` | Get a runbook by slug — optionally guard by version |
+| `list_runbooks` | List runbooks — optional `status`, `category`, `team`, applicability filters |
+| `list_runbooks_by_category` | List runbooks for a specific category (uses byCategory index) |
+| `list_runbooks_by_team` | List runbooks for a specific team (uses byTeam index) |
+| `delete_runbook` | Soft-delete a runbook — sets status to `deprecated` |
+
+**Runbook status values:** `draft | published | deprecated`
+
+**Example invocations:**
+
+```
+# Get a specific runbook
+get_runbook(name="deploy-production", version="1.0.0")
+
+# List all published deployment runbooks
+list_runbooks(status="published", category="deployment")
+
+# List all runbooks for the core team
+list_runbooks_by_team(team="core")
+
+# List all published runbooks in the quality category
+list_runbooks_by_category(category="quality", status="published")
+
+# Soft-delete a runbook
+delete_runbook(name="old-process-v1")
+```
+
+**Upsert a runbook (minimal example):**
+
+```
+upsert_runbook(
+  name="onboard-agent",
+  description="Standard protocol to onboard a new agent to the fleet",
+  version="1.0.0",
+  status="draft",
+  category="onboarding",
+  tags=["agent", "onboarding", "fleet"],
+  content="# Onboard Agent\n\n...",
+  phases=[{ name="prep", description="Preparation phase", steps=[], gate=null }],
+  inputs=[],
+  outputs=[],
+  applicability={ orchestrators=["omega"], business_units=[], use_cases=[] },
+  author="omega",
+  team="core",
+  related_skills=[],
+  related_agents=[],
+  linked_templates=[]
+)
+```
+
+### Stats
+
+| Tool | Description |
+|------|-------------|
+| `get_stats` | Registry overview — counts per table including runbooks breakdown |
+
+**New in 1.1.0:** `get_stats` response includes `runbooks_count`:
+
+```json
+{
+  "teams": 18,
+  "agents": 148,
+  "skills": 328,
+  "plugins": 16,
+  "hooks": 22,
+  "runbooks_count": {
+    "total": 0,
+    "by_status": {
+      "draft": 0,
+      "published": 0,
+      "deprecated": 0
+    },
+    "by_category": {}
+  },
+  "total": 532
+}
+```
+
+---
+
+## Schema
+
+### runbooks table (new in 1.1.0)
+
+| Field | Type | Notes |
+|-------|------|-------|
+| `name` | string | Unique slug — upsert key |
+| `description` | string | Purpose summary |
+| `version` | string | Semantic version |
+| `status` | `draft \| published \| deprecated` | Lifecycle state |
+| `category` | string | e.g. `deployment`, `quality`, `onboarding` |
+| `tags` | string[] | Searchable tags |
+| `content` | string | Full markdown content |
+| `phases` | Phase[] | Ordered phases with steps and gates |
+| `inputs` | RunbookInput[] | Required input parameters |
+| `outputs` | RunbookOutput[] | Produced output artifacts |
+| `applicability` | object | `orchestrators`, `business_units`, `use_cases` slugs |
+| `author` | string | Author slug |
+| `team` | string | Owning team slug |
+| `related_skills` | string[] | Referenced skill slugs |
+| `related_agents` | string[] | Referenced agent slugs |
+| `linked_templates` | LinkedTemplate[] | Templates used within this runbook |
+| `embedding` | float64[1536] | OpenAI ada-002 embedding for hybrid search |
+
+**Indexes:** `byName`, `byStatus`, `byCategory`, `byTeam`
+**Vector index:** `byEmbedding` (1536 dimensions, filter fields: `status`, `category`, `team`)
+
+### templates table (enriched in 1.1.0)
+
+Added optional `template_type` discriminator field:
+- Values: `mission | document | checklist`
+- Default backfill: `"mission"` for all existing templates
+
+---
+
+## Requirements
+
+- [Bun](https://bun.sh) runtime (server is authored in TypeScript for Bun)
+- `CONVEX_URL` environment variable pointing to the VantageRegistry Convex deployment
+
+---
+
+## Changelog
+
+See [CHANGELOG.md](../CHANGELOG.md) at the repo root.
+
+---
+
+Orchestrator: Omega — VantageOS Team | 2026-05-19

package/package.json

@@ -0,0 +1,31 @@
+{
+  "name": "@vantageos/vantage-registry-mcp",
+  "version": "1.1.0",
+  "description": "MCP server exposing VantageRegistry Convex functions as Claude Code tools",
+  "type": "module",
+  "bin": {
+    "vantage-registry": "./server.ts"
+  },
+  "scripts": {
+    "build": "tsc --project tsconfig.json",
+    "dev": "bun run server.ts"
+  },
+  "files": [
+    "server.ts",
+    "server.js",
+    "README.md"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.28.0",
+    "convex": "^1.34.0",
+    "dotenv": "^16.0.0",
+    "zod": "^4.3.6"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "typescript": "^5.9.3"
+  }
+}