feat: REST API parity with MCP tools — 30+ endpoints#46
Merged
howethomas merged 3 commits intomainfrom Apr 15, 2026
Merged
Conversation
Expand the REST API from 7 basic CRUD endpoints to full parity with all 30 MCP tools. Developers can now choose between MCP (for AI assistants) and REST (for scripts, web apps, integrations) with identical capabilities. New endpoints: - PATCH /vcons/:uuid — update metadata - POST /vcons/:uuid/dialog, /analysis, /attachments — sub-resources - GET/PUT/DELETE /vcons/:uuid/tags — per-vCon tag management - GET /tags, /tags/search — tag discovery - GET /vcons/search/content, /semantic, /hybrid — all search modes - GET /database/shape, /stats, /size, /health — operational - POST /database/analyze — query plan analysis - GET /analytics, /growth, /content, /tags, /attachments — reporting - GET /schema, /examples/:type — documentation Architecture: - Refactor monolithic rest-router.ts into modular route files - Extract generateEmbedding() to shared src/utils/embeddings.ts - Add VConService.update() with hook lifecycle (fixes MCP bypass) - Extend RestApiContext with dbInspector, dbAnalytics, dbSizeAnalyzer - Add response envelope helpers, validation utils, pagination middleware - Add PATCH to CORS allowed methods, X-Total-Count header support Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Add comprehensive HTTP-level test coverage for every REST route using supertest with fully mocked dependencies (no database required). Test files: - tests/api/helpers.ts — test harness (createTestApp, mock factories, sample data) - tests/api/routes/vcons.test.ts — CRUD + sub-resources (23 tests) - tests/api/routes/tags.test.ts — tag management + discovery (11 tests) - tests/api/routes/search.test.ts — content, semantic, hybrid search (9 tests) - tests/api/routes/database.test.ts — DB ops + analytics (12 tests) - tests/api/routes/schema.test.ts — health, version, schema, examples (7 tests) Fixes: - Fix Koa router prefix double-mounting for /database and /analytics routes - Add supertest + @types/supertest to devDependencies Total: 691 tests pass (42 files), up from 629 tests (37 files). Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Documentation audit found 23 files with issues after REST API expansion. Critical fixes: - README.md: endpoint table updated from 6 to 30+ routes, tool count 27→30, curl examples fixed from vcon 0.3.0→0.4.0, REST description expanded - CLAUDE.md: added src/api/ directory tree, Koa to tech list - docs/api/index.md: REST component box updated, spec version -00→-02 - docs/development/architecture.md: added REST layer to diagram, fixed vcon version 0.3.0→0.4.0 - docs/development/testing.md: tool count 11→30, added REST test mention Consistency fixes (23 files): - All vcon version references: 0.3.0→0.4.0 across 15 doc files - All spec references: draft-ietf-vcon-vcon-core-00→-02 across 12 files - docs/api/rest-api.md: Python example fixed JS template literal syntax - .env.example: added REST_API_BASE_PATH, REST_API_ENABLED, CORS_ORIGIN - docs/reference/QUICK_REFERENCE.md: session_id type fixed to object, must_support renamed to critical - docs/guide/getting-started.md: tool list expanded, REST API section added Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
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
1 participant
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.
Summary
What changed
REST API (src/api/):
rest-router.tsinto modular route files (routes/vcons.ts,tags.ts,search.ts,database.ts,analytics.ts,schema.ts)context.ts,response.ts,validation.ts,middleware/pagination.tsBusiness logic (src/services/):
VConService.update()withbeforeUpdate/afterUpdatehook lifecycle (fixes existing MCP handler that bypassed VConService)Shared utilities (src/utils/):
generateEmbedding()from MCP search handler tosrc/utils/embeddings.ts— used by both MCP and RESTTests (tests/api/):
helpers.tswithcreateTestApp(), mock factories for all 7 RestApiContext depsDocs (23 files):
Test plan
npm run build— clean TypeScript compilationnpm test— 691 tests pass (42 files)MCP_TRANSPORT=http🤖 Generated with Claude Code