architecture · supabase_json
Oro Docs MCP architecture
architecture artifact · for Oro Docs MCP · status draft
components
| id | name | inputs | outputs | purpose | failure behavior |
|---|---|---|---|---|---|
| CMP-001 | Indexer | - Oro documentation repo path | - data/chunks.json - data/search-index.json - data/metadata.json | Walk docs source and build chunk/index metadata. | Fail with file path and parser error summary; do not partially overwrite known-good index unless build succeeds. |
| CMP-002 | RST Extractor | - .rst file content | - Document chunks | Extract titles, headings, sections, directives, and code blocks from .rst files. | Fall back to whole-file text chunk with warning. |
| CMP-003 | Search Service | - query - optional limit - optional section - optional corpus - optional mode | - ranked result list | Serve ranked query results over local chunks. | Return structured MCP error if index is missing and recommend refresh command. |
| CMP-004 | Virtual Docs Filesystem | - allowlisted command string | - truncated stdout | Run safe read-only list/search/read commands against the docs root. | Reject unsupported commands, path traversal, and write-like flags. |
| CMP-005 | MCP Server | - MCP tool calls | - MCP tool responses | Expose search_oro and query_docs_filesystem_oro tools to Codex/Atlas. | Return concise structured errors without leaking host paths beyond configured docs root. |
| CMP-006 | Embedding Indexer | - Document chunks - optional embedding provider config | - data/embeddings.json or local vector store | Generate and persist embeddings for docs/source chunks when credentials are configured. | Record embedding failure and keep keyword search available. |
| CMP-007 | Application Source Indexer | - Oro application source repo path - include/exclude rules | - Source chunks with corpus labels | Index selected OroCommerce application source files as a separate source corpus. | Skip excluded/unreadable paths and report counts. |
| CMP-008 | Evaluation Harness | - evaluation query set - MCP tool calls | - quality and safety report | Run representative retrieval and safety tests before registration. | Fail build or registration gate when required checks miss expected docs or safety tests fail. |
| CMP-009 | Hosted MCP Adapter | - MCP tool calls over hosted transport | - MCP tool responses | Expose hosted MCP endpoints under mcp.bezeliq.ai, including /oro, with stable routing, health, and discovery behavior. | Return structured service errors and preserve local testability. |
| CMP-009A | Browser Catalog Site | - MCP card registry - tool metadata - status metadata | - HTML catalog page - capability detail pages - connection snippets | Render a human-readable MCP catalog for browser visitors at the root domain. | If dynamic status checks fail, render static catalog metadata with status marked unknown. |
| CMP-010 | MCP Card Registry | - cards/*.json | - get_mcp_card tool response and static/discovery card metadata | Serve and validate MCP cards for the hosted server and Oro docs/source capability. | Fail tests if required card fields are missing. |
data model
files
| id | path | shape | purpose |
|---|---|---|---|
| DATA-001 | data/chunks.json | - id: stable hash - url: best-effort public URL - kind: rst|markdown|code|config - path: docs-relative path - title: document title - content: chunk text - section: section heading - line end: optional integer - line start: optional integer | Normalized searchable chunks with source metadata. |
| DATA-002 | data/search-index.json | Serialized local search index. | |
| DATA-003 | data/metadata.json | Index build metadata including source repo path, commit, file counts, and build timestamp. | |
| DATA-004 | data/embeddings.json | Optional semantic vectors keyed by chunk id. | |
| DATA-005 | data/eval-results.json | Retrieval quality and filesystem safety test output. | |
| DATA-006 | cards/mcp.bezeliq.ai.json | Registry-level MCP card with transport, owner, auth, hosted routes, browser catalog metadata, and global safety policy. | |
| DATA-007 | cards/oro-docs.json | Capability-level MCP card with Oro tools, corpora, source repos, examples, and refresh policy. |
routes
| path | type | purpose |
|---|---|---|
| / | browser_catalog | Human-readable overview of BezelIQ MCPs, endpoint URLs, tools, auth, and examples. |
| /cards | json | List available MCP cards. |
| /cards/oro | json | Return Oro MCP card. |
| /oro | mcp_or_browser_negotiated | Serve Oro MCP transport for MCP clients; render Oro endpoint documentation for browser Accept headers if practical. |
| /health | json | Service health. |
projects database entities
| id | name | purpose | minimum fields |
|---|---|---|---|
| PDB-001 | mcp_servers | Registry rows for hosted MCP servers/capabilities such as Oro. | - id - slug - name - base_url - endpoint_path - status - card_ref - created_at - updated_at |
| PDB-002 | mcp_cards | Versioned MCP card metadata for browser catalog and agent discovery. | - id - server_slug - card_version - content - status - published_at |
| PDB-003 | mcp_index_runs | Index/refresh metadata for docs and source corpora. | - id - server_slug - corpus - source_commit - status - file_count - chunk_count - started_at - completed_at |
risks
| id | severity | mitigation | description |
|---|---|---|---|
| RISK-001 | medium | Use pragmatic heading/chunk extraction and preserve raw text fallback. | RST parsing can become overcomplicated. |
| RISK-002 | high | Centralize root resolution and add negative tests for traversal/absolute paths. | Filesystem tool could accidentally expose host filesystem if path checks are weak. |
| RISK-003 | medium | Capture top-level section metadata and allow optional section filtering. | Search may return noisy results across user/admin/developer docs. |
open questions
| id | owner | blocks | status | question |
|---|---|---|---|---|
| OQ-ARCH-001 | justin | Post-M-01 repository hygiene, not initial local build. | open | Should the MCP package be committed as its own Git repo after creation? |
Agent Handoff
Start Here
architecture artifact · for Oro Docs MCP · status draft
Completion Evidence
No explicit evidence field yet. Require tests, screenshots, linked PRs, or reviewed outputs before marking complete.
Components
- Indexer: id: string, name: string, inputs: object, outputs: object, purpose: string, failure_behavior: string
- RST Extractor: id: string, name: string, inputs: object, outputs: object, purpose: string, failure_behavior: string
- Search Service: id: string, name: string, inputs: object, outputs: object, purpose: string, failure_behavior: string
- Virtual Docs Filesystem: id: string, name: string, inputs: object, outputs: object, purpose: string, failure_behavior: string
- MCP Server: id: string, name: string, inputs: object, outputs: object, purpose: string, failure_behavior: string
- Embedding Indexer: id: string, name: string, inputs: object, outputs: object, purpose: string, failure_behavior: string
- Application Source Indexer: id: string, name: string, inputs: object, outputs: object, purpose: string, failure_behavior: string
- Evaluation Harness: id: string, name: string, inputs: object, outputs: object, purpose: string, failure_behavior: string
- Hosted MCP Adapter: id: string, name: string, inputs: object, outputs: object, purpose: string, failure_behavior: string
- Browser Catalog Site: id: string, name: string, inputs: object, outputs: object, purpose: string, failure_behavior: string
- MCP Card Registry: id: string, name: string, inputs: object, outputs: object, purpose: string, failure_behavior: string
Risks
- RISK-001: RST parsing can become overcomplicated.
- RISK-002: Filesystem tool could accidentally expose host filesystem if path checks are weak.
- RISK-003: Search may return noisy results across user/admin/developer docs.
Open Questions
- OQ-ARCH-001: id: string, owner: string, blocks: string, status: string, question: string
Structured Payload
Machine-readable source fields
risks
| id | severity | mitigation | description |
|---|---|---|---|
| RISK-001 | medium | Use pragmatic heading/chunk extraction and preserve raw text fallback. | RST parsing can become overcomplicated. |
| RISK-002 | high | Centralize root resolution and add negative tests for traversal/absolute paths. | Filesystem tool could accidentally expose host filesystem if path checks are weak. |
| RISK-003 | medium | Capture top-level section metadata and allow optional section filtering. | Search may return noisy results across user/admin/developer docs. |
status
draft
handoff
blocking question ids
No items captured.
ready for coherence review
true
project
id
oro-docs-mcp
name
Oro Documentation MCP
client id
redkey
requirements ref
docs/projects/oro-docs-mcp/artifacts/REQUIREMENTS.json
tooling
commands
| id | name | command | purpose |
|---|---|---|---|
| CMD-001 | build-index | npm run build:index | Rebuild local Oro docs index. |
| CMD-002 | start-mcp | npm run start | Run MCP server. |
| CMD-003 | test | npm test | Run parser, search, and filesystem safety tests. |
| CMD-004 | deploy | npm run deploy | Deploy hosted MCP to mcp.bezeliq.ai. |
security
network
No network required for keyword search/read after repos are cloned. Embedding refresh may use provider network access when explicitly run.
secrets
No credentials required for keyword search or filesystem tools. Embedding generation may use OPENAI_API_KEY or another configured provider key.
filesystem policy
- Resolve all paths under configured docs root.
- Reject
.., absolute paths outside root, drive-letter paths, glob writes, redirects, pipes that imply execution, and unsupported commands. - Allow only read/list/search/text-processing commands needed for docs inspection.
- No write commands, package managers, network calls, process control, or script execution through the filesystem tool.
components
| id | name | inputs | outputs | purpose | failure behavior |
|---|---|---|---|---|---|
| CMP-001 | Indexer | - Oro documentation repo path | - data/chunks.json - data/search-index.json - data/metadata.json | Walk docs source and build chunk/index metadata. | Fail with file path and parser error summary; do not partially overwrite known-good index unless build succeeds. |
| CMP-002 | RST Extractor | - .rst file content | - Document chunks | Extract titles, headings, sections, directives, and code blocks from .rst files. | Fall back to whole-file text chunk with warning. |
| CMP-003 | Search Service | - query - optional limit - optional section - optional corpus - optional mode | - ranked result list | Serve ranked query results over local chunks. | Return structured MCP error if index is missing and recommend refresh command. |
| CMP-004 | Virtual Docs Filesystem | - allowlisted command string | - truncated stdout | Run safe read-only list/search/read commands against the docs root. | Reject unsupported commands, path traversal, and write-like flags. |
| CMP-005 | MCP Server | - MCP tool calls | - MCP tool responses | Expose search_oro and query_docs_filesystem_oro tools to Codex/Atlas. | Return concise structured errors without leaking host paths beyond configured docs root. |
| CMP-006 | Embedding Indexer | - Document chunks - optional embedding provider config | - data/embeddings.json or local vector store | Generate and persist embeddings for docs/source chunks when credentials are configured. | Record embedding failure and keep keyword search available. |
| CMP-007 | Application Source Indexer | - Oro application source repo path - include/exclude rules | - Source chunks with corpus labels | Index selected OroCommerce application source files as a separate source corpus. | Skip excluded/unreadable paths and report counts. |
| CMP-008 | Evaluation Harness | - evaluation query set - MCP tool calls | - quality and safety report | Run representative retrieval and safety tests before registration. | Fail build or registration gate when required checks miss expected docs or safety tests fail. |
| CMP-009 | Hosted MCP Adapter | - MCP tool calls over hosted transport | - MCP tool responses | Expose hosted MCP endpoints under mcp.bezeliq.ai, including /oro, with stable routing, health, and discovery behavior. | Return structured service errors and preserve local testability. |
| CMP-009A | Browser Catalog Site | - MCP card registry - tool metadata - status metadata | - HTML catalog page - capability detail pages - connection snippets | Render a human-readable MCP catalog for browser visitors at the root domain. | If dynamic status checks fail, render static catalog metadata with status marked unknown. |
| CMP-010 | MCP Card Registry | - cards/*.json | - get_mcp_card tool response and static/discovery card metadata | Serve and validate MCP cards for the hosted server and Oro docs/source capability. | Fail tests if required card fields are missing. |
data model
files
| id | path | shape | purpose |
|---|---|---|---|
| DATA-001 | data/chunks.json | - id: stable hash - url: best-effort public URL - kind: rst|markdown|code|config - path: docs-relative path - title: document title - content: chunk text - section: section heading - line end: optional integer - line start: optional integer | Normalized searchable chunks with source metadata. |
| DATA-002 | data/search-index.json | Serialized local search index. | |
| DATA-003 | data/metadata.json | Index build metadata including source repo path, commit, file counts, and build timestamp. | |
| DATA-004 | data/embeddings.json | Optional semantic vectors keyed by chunk id. | |
| DATA-005 | data/eval-results.json | Retrieval quality and filesystem safety test output. | |
| DATA-006 | cards/mcp.bezeliq.ai.json | Registry-level MCP card with transport, owner, auth, hosted routes, browser catalog metadata, and global safety policy. | |
| DATA-007 | cards/oro-docs.json | Capability-level MCP card with Oro tools, corpora, source repos, examples, and refresh policy. |
routes
| path | type | purpose |
|---|---|---|
| / | browser_catalog | Human-readable overview of BezelIQ MCPs, endpoint URLs, tools, auth, and examples. |
| /cards | json | List available MCP cards. |
| /cards/oro | json | Return Oro MCP card. |
| /oro | mcp_or_browser_negotiated | Serve Oro MCP transport for MCP clients; render Oro endpoint documentation for browser Accept headers if practical. |
| /health | json | Service health. |
projects database entities
| id | name | purpose | minimum fields |
|---|---|---|---|
| PDB-001 | mcp_servers | Registry rows for hosted MCP servers/capabilities such as Oro. | - id - slug - name - base_url - endpoint_path - status - card_ref - created_at - updated_at |
| PDB-002 | mcp_cards | Versioned MCP card metadata for browser catalog and agent discovery. | - id - server_slug - card_version - content - status - published_at |
| PDB-003 | mcp_index_runs | Index/refresh metadata for docs and source corpora. | - id - server_slug - corpus - source_commit - status - file_count - chunk_count - started_at - completed_at |
artifact type
ARCHITECTURE
open questions
| id | owner | blocks | status | question |
|---|---|---|---|---|
| OQ-ARCH-001 | justin | Post-M-01 repository hygiene, not initial local build. | open | Should the MCP package be committed as its own Git repo after creation? |
schema version
1.0
architecture summary
stack
parser
Custom pragmatic RST section extractor with directive handling
search
Local keyword/BM25 search plus optional semantic/hybrid retrieval
hosting
mcp.bezeliq.ai, preferably Cloudflare Worker/Pages Function or a small Node service behind Cloudflare
runtime
Node.js/TypeScript MCP server
storage
Local JSON index files under the MCP package data directory
database
Projects database for MCP registry/card/status/refresh metadata
source docs
C:/Users/jstnk/Downloads/cc/projects/documentation
browser catalog
Static or server-rendered HTML/JSON registry at / plus capability detail pages such as /oro/docs or /oro when requested by browser
application source
C:/Users/jstnk/Downloads/cc/projects/orocommerce-application
approach
Build a hosted BezelIQ MCP capability registry at https://mcp.bezeliq.ai/ with a browser-readable catalog at the root and MCP endpoints under capability paths such as /oro. The Oro MCP indexes Oro documentation and selected Oro application source files. A separate indexer converts Sphinx/RST docs, code examples, and opt-in source files into local/generated keyword and optional semantic indexes. The MCP exposes search, constrained read-only inspection tools, and MCP card metadata, with local development support.
repo roots
- C:/Users/jstnk/Downloads/cc/projects/oro-docs-mcp
major decisions
| id | reason | decision | alternatives rejected |
|---|---|---|---|
| ADR-001 | The MCP is reusable tooling and should not add vendored Oro docs/index noise to RedKey. | Create the MCP as a sibling repo/package instead of inside RedKey. | - Implement directly under RedKey scripts - Place Oro docs inside RedKey |
| ADR-002 | Exact Oro class, bundle, command, and config names need keyword search, while conceptual questions benefit from semantic search. | Use hybrid retrieval as the complete target while preserving keyword-only fallback. | - Embedding-only search - Live web search - Keyword-only final scope |
| ADR-003 | Agents need exact docs inspection but not host filesystem or write access. | Implement a constrained read-only virtual filesystem tool rather than arbitrary shell execution. | - Expose unrestricted shell - Only expose semantic search snippets |
| ADR-004 | Humans who open the root in a browser should understand available MCPs and agents should have stable endpoint/card URLs. | Use mcp.bezeliq.ai as the BezelIQ MCP capability registry root, with /oro as the Oro endpoint. | - Local-only MCP - Bundling MCP into RedKey agent runner |
| ADR-005 | Cards make the MCP discoverable and governable: tools, corpora, transport, safety, owner, refresh, and examples are explicit. | Publish MCP cards as first-class capability metadata. | - README-only documentation - Implicit tool discovery only |
| ADR-006 | Justin specified the database is the Projects database. Registry/card/status metadata belongs with project/capability management, while source corpora remain external checkouts. | Use the Projects database for MCP registry state. | - New MCP-only database - RedKey platform tables as the primary registry store - Storing full docs corpus in database rows |