requirements · supabase_json
Oro Docs MCP requirements
[object Object]
open questions
| id | owner | status | default | question |
|---|---|---|---|---|
| OQ-REQ-001 | atlas | answered | Use OpenAI embeddings when configured, but keep keyword-only operation as the baseline. | Which embedding provider should semantic search use first? |
Agent Handoff
Start Here
[object Object]Completion Evidence
No explicit evidence field yet. Require tests, screenshots, linked PRs, or reviewed outputs before marking complete.
Open Questions
- OQ-REQ-001: id: string, owner: string, status: string, default: string, question: string
Structured Payload
Machine-readable source fields
handoff
blocking question ids
No items captured.
ready for architecture
true
project
id
oro-docs-mcp
name
Oro Documentation MCP
client id
redkey
intent ref
docs/projects/oro-docs-mcp/artifacts/INTENT.json
intake triage ref
docs/projects/oro-docs-mcp/artifacts/INTAKE_TRIAGE.json
summary
outcome
Codex/Atlas can connect to https://mcp.bezeliq.ai/, ask Oro questions, search relevant docs and selected application source, and read exact source files without web browsing or manual repo navigation.
problem
Agents need fast, grounded access to Oro documentation comparable to the existing Hedera documentation MCP.
primary users
- Justin
- Atlas-Codex
- RedKey worker/reviewer agents
features
| id | name | priority | acceptance | description |
|---|---|---|---|---|
| F-01 | Docs Corpus Index | must | - Indexer walks the local Oro documentation checkout.
- Indexer includes .rst, .md, and selected code/example file types.
- Chunks include path, title, section, content, and source type.
- Index can be rebuilt with one command. | Index Oro documentation files into searchable chunks with stable source metadata. |
| F-02 | RST-Aware Extraction | must | - Top-level and section headings are detected.
- Sphinx directives are handled without destroying surrounding text.
- Code blocks are preserved as searchable content.
- toctree, include, image, ref, and doc syntax does not break indexing. | Extract useful structure from Sphinx/reStructuredText documentation. |
| F-03 | Search Tool | must | - search_oro accepts a plain-language or keyword query.
- Results include title, local path, snippet, score/rank, and best-effort public URL.
- Results favor exact Oro docs over code examples for conceptual queries.
- Search works offline against the local index. | Expose an MCP search tool for Oro documentation. |
| F-04 | Read-Only Docs Filesystem Tool | must | - query_docs_filesystem_oro supports safe read/search/list commands such as rg, grep, find, tree, ls, cat, head, tail, sed, awk, wc, sort, uniq, and cut.
- Commands are rooted at the virtual docs root and cannot write files.
- Output is truncated to a predictable size.
- The tool documents that calls are stateless. | Expose a constrained read-only filesystem query interface over the Oro docs corpus. |
| F-05 | MCP Registration | should | - Local MCP server can be started with a documented command. - Codex MCP configuration snippet is provided. - Smoke test confirms tools appear and can search/read Oro docs. | Make the MCP available to Codex/Atlas in the local environment. |
| F-06 | Refresh and Maintenance | should | - Refresh command rebuilds the index deterministically. - Index metadata records source repo path and commit. - Failure output identifies unreadable files or parser issues. | Support refreshing the index after Oro docs repo updates. |
| F-07 | Semantic and Hybrid Search | must | - Embedding generation is an explicit refresh step and can be skipped when credentials are unavailable. - Hybrid search combines keyword and semantic signals instead of replacing exact-match retrieval. - The MCP degrades cleanly to keyword search when embeddings are unavailable. - Results identify whether a match came from docs, code examples, or application source. | Add semantic search and hybrid ranking over indexed docs/source chunks when embedding credentials are available. |
| F-08 | Oro Application Source Corpus | must | - Application source indexing is opt-in and configured separately from official docs indexing. - Search results label application-source matches distinctly from documentation matches. - Source indexing excludes secrets, generated/vendor-heavy paths, caches, build outputs, and binary assets. - Users can filter to docs-only, source-only, or all corpora. | Index selected OroCommerce application source files as a separate corpus for implementation-oriented questions. |
| F-09 | Quality Evaluation Suite | must | - Evaluation queries cover developer, backend, frontend, cloud, user, API, and bundle docs. - Evaluation checks confirm known documents appear in top results for selected queries. - Filesystem tool safety tests are part of the required test suite. - Registration smoke tests verify both MCP tools are callable. | Maintain representative Oro queries and expected source coverage to prevent search regressions. |
| F-10 | Hosted MCP Endpoint | must | - https://mcp.bezeliq.ai/ renders a human-readable BezelIQ MCP catalog in a browser.
- The catalog explains what MCP is, which BezelIQ MCPs are available, how to connect to them, and what tools each exposes.
- https://mcp.bezeliq.ai/oro is the Oro MCP endpoint or endpoint landing page with connection details.
- The service exposes the Oro docs MCP without requiring agents to run a local process.
- Deployment config keeps source/index refresh credentials server-side.
- Smoke tests confirm a remote MCP client can call the Oro tools. | Deploy the complete MCP behind https://mcp.bezeliq.ai/ with a browser-friendly root catalog and stable MCP endpoint routing. |
| F-10A | Browser Catalog | must | - Root page lists all available BezelIQ MCPs as capability entries.
- Each entry shows endpoint URL, status, purpose, exposed tools, auth requirements, and example prompts.
- Each entry links to its MCP card JSON and connection snippet.
- The page is usable without login for public/summary metadata and does not expose secrets or private indexes.
- The Oro page documents search_oro, query_docs_filesystem_oro, and get_mcp_card with input examples. | Provide a simple documentation site at the MCP root for humans who visit in a browser. |
| F-11 | MCP Cards | must | - At least one server-level MCP card describes mcp.bezeliq.ai transport, version, auth, and ownership.
- An Oro Docs MCP card describes tools, corpora, source repos, refresh cadence, safety boundaries, and example prompts.
- Cards are stored in the MCP package and can also be mirrored into RedKey capabilities/definitions if needed.
- Cards are validated as JSON and referenced from README/config docs. | Publish machine-readable MCP cards for discovery, governance, and agent assignment. |
| F-12 | Projects Database Registry State | must | - Architecture names the Projects database as the MCP registry database. - No new database is introduced for MCP registry state. - Hosted root catalog can read MCP listing/card/status metadata from the Projects database or generated artifacts synced from it. - Docs/source corpus files remain external filesystem checkouts and are not copied wholesale into the database. | Use the Projects database as the source for hosted MCP registry state, card metadata, endpoint status, and refresh metadata. |
out of scope
- Visual UX or app shell.
- Modifying upstream Oro docs.
- Indexing arbitrary websites.
- Production hosted service.
artifact type
REQUIREMENTS
tool contract
| name | input | output |
|---|---|---|
| search_oro | - mode: keyword|semantic|hybrid optional - limit: integer optional - query: string - corpus: docs|source|all optional - section: string optional | - results: 1 item |
| query_docs_filesystem_oro | - command: string | - stdout: string - truncated: boolean |
| get_mcp_card | - id: string optional | - cards: 1 item |
open questions
| id | owner | status | default | question |
|---|---|---|---|---|
| OQ-REQ-001 | atlas | answered | Use OpenAI embeddings when configured, but keep keyword-only operation as the baseline. | Which embedding provider should semantic search use first? |
schema version
1.0
non functional requirements
| id | category | requirement | verification hint |
|---|---|---|---|
| NFR-001 | safety | MCP runtime must not write to the Oro documentation checkout during normal search/read operations. | Review tool implementation and run write-attempt negative tests. |
| NFR-002 | security | Filesystem query tool must not expose arbitrary host filesystem access. | Path traversal tests and command allowlist tests. |
| NFR-003 | performance | Common search queries should return in under two seconds on the local corpus. | Smoke benchmark over representative queries. |
| NFR-004 | cost | Keyword search and docs filesystem tools must work without paid external APIs; semantic search may use configured credentials. | Run tests with embeddings disabled and with embedding configuration present. |
| NFR-005 | license | Artifacts and MCP docs must acknowledge Oro documentation source licensing and avoid republishing the full corpus as a generated artifact. | README cites source repo/license and MCP returns snippets/paths rather than bundling public docs into RedKey artifacts. |