oscar64-mcp-docs 0.1.2 → 1.0.0

package/README.md

@@ -6,14 +6,36 @@ Local MCP server (Mastra + stdio) exposing Oscar64 documentation and tutorial co
 
 - HTTP-only source syncing (no git dependency)
 - 24h stale checks with remote SHA + local zip hash detection
+- Per-repo sync locking to avoid concurrent write conflicts across multiple server processes
 - Anchored manual retrieval (`docs://oscar64/manual#...`)
+- Unified code file URIs (`code://oscar/...`, `code://sample/...`, `code://tutorial/...`) for agent-facing results
 - Tutorial metadata generated from folder structure and source previews
-- Generic concept classifier with evidence + concept-derived categories
+- Deterministic faceted classifier (primary track + facets + evidence + confidence)
 - MiniSearch-powered doc/tutorial relevance search
 - Ranked code search across all exposed sources
 - Minimal MCP tool responses (`ok` + `data`/`error`)
 - Single canonical file exposure policy (`.c`, `.h`, `.cpp`, `.s`, `.asm`, `.inc`, `.md`, `.txt`)
-- LLM guidance resources (`index://quickstart`, `index://tooling-guide`, `index://contracts`, `index://errors`)
+- Index discovery tool for navigation/catalog (`list_indexes`)
+
+## Cache and Sync Layout
+
+Cache root:
+
+- `OSCAR_MCP_CACHE_DIR` (if set)
+- default: `~/.cache/oscar-mcp`
+
+Directory layout under cache root:
+
+- `sources/<repo>/current` -> current unpacked repo content
+- `meta/<repo>.json` -> sync metadata (`lastRemoteSha`, `resolvedSha`, `lastZipHash`, timestamps)
+- `meta/<repo>.lock` -> sync lock file used to serialize per-repo updates across processes
+- `index/` -> generated index artifacts
+
+Lock behavior:
+
+- lock acquisition uses an exclusive create on `meta/<repo>.lock`
+- waits up to 5 minutes for a lock holder
+- treats locks older than 30 minutes as stale and removes them
 
 ## Development
 
@@ -54,8 +76,14 @@ The executable entry is built to `dist/stdio.js`.
 
 Primary tools:
 
-- `search(query, limit)` -> unified doc/tutorial/code search with strict fields (doc/tutorial hits include `title`, `snippet`; code hits include `line_start`, `line_end`, `snippet`)
-- `read_uri(uri, binary_mode, max_base64_bytes)` -> strict text/binary read response for any URI returned by `search`
+- `search(query, limit, system, include_details)` -> unified manual/code search with strict hit fields (`source`, `uri`, `title`, `snippet`, `score`, `classification_summary`), optional `referenced_files` as `code://...` URIs readable by `read_uri`, and optional `classification_details`; `system` defaults to `c64` and supports `all` for cross-system results
+- `read_uri(uri, binary_mode, max_base64_bytes)` -> returns `ok + data` where `data.content_type` is `text` or `binary` for `docs://...` and `code://...`
+- `list_indexes(type, system)` -> lists `topics`/`tutorials`/`samples`/`headers` entries; `type` defaults to `headers`, `system` defaults to `c64`, and `system=all` returns cross-system indexes
+
+URI guidance:
+
+- manual/docs: `docs://...`
+- code files: `code://oscar/...`, `code://sample/...`, and `code://tutorial/...`
 
 Standard tool output envelope:
 
@@ -63,12 +91,9 @@ Standard tool output envelope:
 - `data`: tool payload on success
 - `error`: structured error payload on failure
 
-Reference resources:
+Index discovery:
 
-- `index://quickstart`
-- `index://tooling-guide`
-- `index://contracts`
-- `index://errors`
+- `list_indexes(type)` returns only `docs://` and `code://` URIs that can be read directly with `read_uri`.
 
 ## Versioning
 
@@ -107,13 +132,13 @@ Optional env vars:
 - `NPM_TAG` (default `latest`)
 - `NPM_OTP` (for 2FA)
 
-## Tutorial Classification Config
+## Classification Config
 
-Classification policy is data-driven in:
+Classification policy and deterministic scoring are data-driven in:
 
-- `src/config/tutorial-classification.ts`
+- `src/config/classification-v2.ts`
 
 This file defines:
 
-- factual concept rules (`CONCEPT_RULES`) using regex patterns + evidence reasons
-- concept groups for top-level categories (`CATEGORY_FROM_CONCEPTS`)
+- weighted facet rules and primary-track inference
+- tutorial ID band seeds and precedence tie-breaks