ai-spector 0.8.1 → 0.8.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ai-spector",
-  "version": "0.8.1",
+  "version": "0.8.2",
   "description": "Cursor-first documentation workflow: traceability graph, SRS/basic/detail design templates, and ai-spector CLI",
   "type": "module",
   "license": "MIT",

package/scaffold/claude/CLAUDE.md

@@ -1,51 +1,64 @@
 # AI Spector — Claude Agent Rules
 
-You are working in an **AI Spector** managed project. The agent workflow is: read skills, run `npx ai-spector` CLI, report results. You do not write doc content from scratch — CLI + skills do the work.
+You are working in an **AI Spector** managed project. The agent workflow is: read skills, call **MCP tools** (preferred) or `npx ai-spector` CLI (fallback), report results. You do not write doc content from scratch — MCP tools / CLI + skills do the work.
 
 Enable all skills under `.claude/skills/` before starting.
 
 ## Mandatory Rules
 
-### 1. Refresh index before any staleness check
+### 1. MCP first, CLI fallback
+
+When the `ai-spector` MCP server is available, **call the MCP tool** instead of shelling out to `npx ai-spector`.
+
+| Operation | MCP tool | CLI fallback |
+|-----------|----------|--------------|
+| Re-index project | `index({})` | `npx ai-spector index` |
+| Merge knowledge → graph | `graph_merge({ fromKnowledge: true })` | `npx ai-spector graph merge --from-knowledge` |
+| Validate graph | `graph_validate({})` | `npx ai-spector graph validate` |
+| Impact analysis | `graph_impact({ originId, change })` | `npx ai-spector graph impact …` |
+| Walk graph from node | `graph_query({ id })` | `npx ai-spector graph query <id> --json` |
+| **Analyze data-source** | *(CLI only — no MCP tool)* | `npx ai-spector analyze` |
+
+### 2. Refresh index before any staleness check
 
 Before checking translation status, pending queue, or "what's outdated":
 
-```bash
-npx ai-spector index
+```
+index({})                    # MCP preferred
+npx ai-spector index         # CLI fallback
 ```
 
 Then read the queue. **Never read `.ai-spector/.docflow/translation-queue/pending.json` without running index first** — the queue is only accurate after indexing.
 
-### 2. Check impact before finishing any doc edit
+### 3. Check impact before finishing any doc edit
 
 After editing any file under `docs/srs/`, `docs/basic-design/`, or `docs/detail-design/`, run impact before closing the task:
 
-```bash
-npx ai-spector graph impact --git --change content_change --json
+```
+graph_impact({ git: true, change: "content_change" })   # MCP preferred
+npx ai-spector graph impact --git --change content_change --json  # CLI fallback
 ```
 
-Then run index to refresh the translation queue:
+Then refresh index:
 
-```bash
-npx ai-spector index
+```
+index({})
 ```
 
 Skip only when the user explicitly says it was a typo-only fix with no traceability concern.
 
-### 3. Use CLI and graph — not file search
-
-When you need to find, query, or understand the project graph:
+### 4. Use MCP/graph — not file search
 
-| Need | Use |
-|------|-----|
-| Find what needs regeneration | `npx ai-spector graph impact` |
-| Find doc/section/node by exact ID | `npx ai-spector graph query <id> --json` |
-| Find doc/section/node by concept | `graph_query_fuzzy(query: "…")` (MCP) — requires CocoIndex |
-| Search docs by meaning | `docs_search(query: "…")` (MCP) — requires CocoIndex |
-| Check graph health | `npx ai-spector graph validate` |
-| See pending translations | `npx ai-spector lang queue pending --json` (after index) |
+| Need | MCP (preferred) | CLI fallback |
+|------|-----------------|--------------|
+| Find what needs regeneration | `graph_impact({ git: true, change: "content_change" })` | `npx ai-spector graph impact --git --json` |
+| Find node by exact ID | `graph_query({ id: "…" })` | `npx ai-spector graph query <id> --json` |
+| Find node by concept | `graph_query_fuzzy(query: "…")` — requires CocoIndex | — |
+| Search docs by meaning | `docs_search(query: "…")` — requires CocoIndex | — |
+| Check graph health | `graph_validate({})` | `npx ai-spector graph validate` |
+| See pending translations | *(CLI only)* | `npx ai-spector lang queue pending --json` (after index) |
 
-**Only fall back to `grep` or `Read` when the CLI returns no results or you need raw file content for editing.**
+**Only fall back to `grep` or `Read` when the tool returns no results or you need raw file content for editing.**
 
 ## Skill → task mapping
 
@@ -64,13 +77,25 @@ When you need to find, query, or understand the project graph:
 | Resolve translations | `ai-spector-resolve-translation` |
 | Resolve comments | `ai-spector-resolve-comments` |
 
-## CLI quick reference
+## Quick reference
+
+### MCP tools (prefer these)
+
+| Tool | Purpose |
+|------|---------|
+| `index({})` | Refresh fingerprints + translation queue |
+| `graph_merge({ fromKnowledge: true })` | Merge knowledge.json into graph |
+| `graph_validate({})` | Check graph integrity |
+| `graph_impact({ git: true, change: "content_change" })` | Impact of current git diff |
+| `graph_query({ id: "…" })` | Walk graph from a node |
+
+### CLI (fallback / MCP-unavailable or no tool equivalent)
 
 ```bash
-npx ai-spector analyze              # ingest data-source, build graph
-npx ai-spector index                # refresh fingerprints + translation queue
-npx ai-spector graph validate       # check graph integrity
-npx ai-spector graph impact --git --json   # impact of current git diff (+ semantic suggestions if CocoIndex configured)
+npx ai-spector analyze              # ingest data-source, build graph (no MCP equivalent)
+npx ai-spector index                # fallback for index({})
+npx ai-spector graph validate       # fallback for graph_validate({})
+npx ai-spector graph impact --git --json   # fallback for graph_impact({ git: true })
 npx ai-spector lang queue pending --json   # pending translation jobs
 npx ai-spector setup --check        # audit project setup
 npx ai-spector template list        # list installed packs + active
@@ -81,11 +106,9 @@ npx ai-spector template use <name>  # switch active pack (use "builtin" to rever
 # CocoIndex (opt-in — requires Python 3.11+)
 npx ai-spector cocoindex setup      # scaffold pipeline into project
 npx ai-spector cocoindex index      # run pipeline (update embeddings)
-npx ai-spector cocoindex search --query "login flow"   # semantic search
-npx ai-spector cocoindex query-fuzzy --query "login"   # natural language → graph node + subgraph
 ```
 
-On CLI failure: show the output, offer fix / workaround / pause. Do not invent results.
+On MCP tool or CLI failure: show the output, offer fix / workaround / pause. Do not invent results.
 
 ## Pipeline order
 

package/scaffold/cursor/skills/ai-spector/SKILL.md

@@ -12,6 +12,21 @@ description: >-
 
 **Workflow:** [../../WORKFLOW.md](../../WORKFLOW.md) · **Router:** [_skill-router.md](../_skill-router.md)
 
+## Invocation rule — MCP first, CLI fallback
+
+When the `ai-spector` MCP server is enabled (`.cursor/mcp.json` or `.mcp.json` lists it), **call the MCP tool** instead of shelling out to `npx ai-spector`. MCP returns structured JSON, avoids spawning a Node process, and is the preferred channel for agents.
+
+| Operation | MCP tool | CLI fallback |
+|-----------|----------|--------------|
+| Re-index project | `index({})` | `npx ai-spector index` |
+| Merge knowledge → graph | `graph_merge({ fromKnowledge: true })` | `npx ai-spector graph merge --from-knowledge` |
+| Validate graph | `graph_validate({})` | `npx ai-spector graph validate` |
+| Impact analysis | `graph_impact({ originId, change })` | `npx ai-spector graph impact …` |
+| Walk graph from node | `graph_query({ id, … })` | `npx ai-spector graph query <id> --json` |
+| **Analyze data-source** | *(no MCP tool — CLI only)* | `npx ai-spector analyze` |
+
+Use CLI **only** when: MCP server is not configured, the tool errors and MCP is unavailable, or the operation has no MCP equivalent (e.g. `analyze`).
+
 ## CLI and tool failure (non-negotiable)
 
 When `npx ai-spector` exits non-zero, required `--json` is invalid, or a required MCP/terminal step fails:
@@ -27,7 +42,7 @@ When `npx ai-spector` exits non-zero, required `--json` is invalid, or a require
 |------|------|
 | Config (languages, paths) | `.ai-spector/docflow.config.json` |
 | Graph | `.ai-spector/graph/traceability.graph.json` |
-| Query | `npx ai-spector graph query <id> --json` |
+| Query | `graph_query({ id })` MCP · fallback: `npx ai-spector graph query <id> --json` |
 | Templates | `.ai-spector/templates/` |
 | Doc output | `docs/srs/{lang.code}/` · `docs/basic-design/{lang.code}/` |
 

package/scaffold/cursor/skills/ai-spector-graph/SKILL.md

@@ -36,7 +36,7 @@ Read **one** runbook under `references/` for the user’s intent, then execute i
 
 ```
 - [ ] Matched runbook read completely
-- [ ] CLI from project root (npx ai-spector)
+- [ ] MCP first (ai-spector server) → CLI fallback (npx ai-spector) — see ai-spector/SKILL.md#invocation-rule
 - [ ] On failure: pause; offer fix / workaround / pause per ai-spector/references/cli-failures.md
 ```
 

package/scaffold/cursor/skills/ai-spector-graph/references/analyze.md

@@ -2,7 +2,7 @@
 
 Ingest `docs/data-source/` and commit knowledge into the traceability graph.
 
-The agent runs all CLI steps below — see [WORKFLOW.md](../../WORKFLOW.md).
+Step 0 (`npx ai-spector analyze`) is **CLI-only** — no MCP equivalent. Steps B (merge, validate) use **MCP when available**.
 
 ## Usage
 
@@ -48,6 +48,15 @@ Creates section/document nodes from templates. Do not ask the user to run this s
 
 ### B. Commit to graph
 
+**MCP (preferred when ai-spector server is configured):**
+
+```
+graph_merge({ fromKnowledge: true })
+graph_validate({})
+```
+
+**CLI fallback:**
+
 ```bash
 npx ai-spector graph merge --from-knowledge
 npx ai-spector graph validate
@@ -69,13 +78,13 @@ Update `state.json`: `analysis.lastRunAt`, `analysis.dataSource`, scope hash. Me
 - `knowledge.json` mirrors extract; graph is authoritative for `/generate-srs`.
 - Gaps recorded in `gaps.json`.
 
-## CLI steps — stop on first failure
+## Steps — stop on first failure
 
-| Step | Command |
-|------|---------|
-| 0 | `npx ai-spector analyze` |
-| B | `npx ai-spector graph merge --from-knowledge` |
-| B | `npx ai-spector graph validate` |
+| Step | MCP (preferred) | CLI fallback |
+|------|-----------------|--------------|
+| 0 | *(CLI only — no MCP tool)* | `npx ai-spector analyze` |
+| B merge | `graph_merge({ fromKnowledge: true })` | `npx ai-spector graph merge --from-knowledge` |
+| B validate | `graph_validate({})` | `npx ai-spector graph validate` |
 
 If any step fails, **pause** and use [cli-failures.md](../../ai-spector/references/cli-failures.md). Do not skip to generate SRS without user choice.
 

package/scaffold/cursor/skills/ai-spector-graph/references/impact.md

@@ -58,15 +58,17 @@ Map regions with the same rules as below (`resolveImpactOrigins` / graph JSON).
 
 ### 3. Run impact per seed, unify report
 
-For each file/region, pick the **most specific** seed (`section` > domain > `document`). Dedupe seeds by id, then:
+For each file/region, pick the **most specific** seed (`section` > domain > `document`). Dedupe seeds by id, then run impact (MCP preferred, CLI fallback):
 
-```bash
-npx ai-spector graph impact <originId> --change content_change --json
 ```
-
-Or once for all seeds:
+graph_impact({ originId: "<id>", change: "content_change" })
+# or for all git seeds at once:
+graph_impact({ git: true, change: "content_change" })
+```
 
 ```bash
+# CLI fallback:
+npx ai-spector graph impact <originId> --change content_change --json
 npx ai-spector graph impact --git --change content_change --json
 ```
 
@@ -89,25 +91,27 @@ Gather context from the message (priority order):
 
 If several nodes match, pick the **most specific** seed: `section` > domain (`useCase`, `feature`, …) > `document`. If still ambiguous, ask **one** short clarifying question (never ask for raw node id format).
 
-## Run impact (CLI)
+## Run impact
 
-After resolving `originId` (one primary seed per region; run again for unrelated regions if needed):
+**Use MCP when the `ai-spector` server is configured. Fall back to CLI otherwise.**
 
-```bash
-npx ai-spector graph impact <originId> --change content_change --json
+### MCP (preferred)
+
+```
+graph_impact({ originId: "<id>", change: "content_change" })
+graph_impact({ git: true, change: "content_change" })
+graph_impact({ file: "docs/srs/3-use-cases.md", heading: "3.2 List Use Case", change: "content_change" })
 ```
 
-Or resolver flags (optional verification):
+### CLI fallback
 
 ```bash
+npx ai-spector graph impact <originId> --change content_change --json
+npx ai-spector graph impact --git --change content_change --json
 npx ai-spector graph impact --file docs/srs/3-use-cases.md --heading "3.2 List Use Case" --json
 ```
 
-Optional report file:
-
-```bash
-npx ai-spector graph impact <originId> --json -o .ai-spector/views/impact-<timestamp>.json
-```
+After resolving `originId` (one primary seed per region; run again for unrelated regions if needed):
 
 1. Parse JSON output:
    - `regenerate` / `review` arrays — traceability impact buckets
@@ -115,7 +119,7 @@ npx ai-spector graph impact <originId> --json -o .ai-spector/views/impact-<times
    - `truncated: true` — BFS hit the propagation cap; warn the user results may be incomplete
    - `resolvedFrom` / `gitSeeds` — which file/heading each seed came from (present with `--file` / `--heading` / `--git`)
 2. Present a table with `projectionPath` per entry.
-3. For each **regenerate** id, suggest `/generate-srs` or `/generate-basic-design` using:
+3. For each **regenerate** id, suggest `/generate-srs` or `/generate-basic-design` using MCP `graph_query({ id: "<thatId>" })` or CLI:
 
 ```bash
 npx ai-spector graph query <thatId> --json

package/scaffold/cursor/skills/ai-spector-graph/references/index.md

@@ -6,8 +6,8 @@ Rebuild **graph**, re-merge **knowledge** staging, and update **document indexes
 
 ## Usage
 
-- `/index` — full CLI refresh (agent runs commands below)
-- User may run: `npx ai-spector index` with flags (see README)
+- `/index` — full refresh via MCP (preferred) or CLI fallback
+- User may run: `npx ai-spector index` with flags (see README) when MCP is unavailable
 
 ## When to use
 
@@ -19,43 +19,34 @@ Rebuild **graph**, re-merge **knowledge** staging, and update **document indexes
 
 **Still requires `/analyze` for:** full knowledge extraction → `knowledge.json` (NFRs, data model, rich descriptions). Index re-merges existing `knowledge.json` when present; warns if SRS changed but knowledge is stale.
 
-## Required Behavior (agent runs CLI)
+## Required Behavior
 
-```bash
-npx ai-spector index
+**Use the MCP tool when the `ai-spector` server is configured. Fall back to CLI only when MCP is unavailable.**
+
+### MCP (preferred)
+
+```
+index({})                              # full refresh
+index({ graphOnly: true })             # structure + knowledge merge only
+index({ docsOnly: true })              # doc indexes only
+index({ skipMerge: true })             # skip knowledge.json merge
+index({ skipDocSemantics: true })      # skip UC/F body parsing
 ```
 
-After **`/generate-srs`** (recommended):
+### CLI fallback
 
 ```bash
 npx ai-spector index
+npx ai-spector index --graph-only
+npx ai-spector index --docs-only
 ```
 
 Index steps (default): registry/bootstrap → knowledge merge → **SRS/docs body extract** → **source hub** → **provenance (`derivedFrom`)** → **business hub** → validate → doc indexes.
 
-**CLI alone is not full semantics:** Index builds structure + parseable meaning. For cross-hub evidence links (`relatesTo`), run **`/link-graph`** after index, then `npx ai-spector graph merge --semantic`. Check gaps with `npx ai-spector graph report --json`.
+**CLI alone is not full semantics:** Index builds structure + parseable meaning. For cross-hub evidence links (`relatesTo`), run **`/link-graph`** after index, then `graph_merge({ semantic: true })` (MCP) or `npx ai-spector graph merge --semantic`. Check gaps with `npx ai-spector graph report --json`.
 
 **Provenance:** UC/F/requirement/actor nodes get **`derivedFrom`** edges to `docs/data-source/**` paths (from `knowledge.json` `sourceRef` / `sourceRefs` / `derivedFrom`, SRS detail `Source:` lines, or inline `docs/data-source/…` mentions). No evidence → no edge.
 
-Flags:
-
-| Flag | Effect |
-|------|--------|
-| `--skip-doc-semantics` | Skip UC/F parsing from `docs/srs` and `docs/basic-design` |
-| `--skip-merge` | Skip `knowledge.json` merge |
-
-Structure + merge only:
-
-```bash
-npx ai-spector index --graph-only
-```
-
-Doc indexes only:
-
-```bash
-npx ai-spector index --docs-only
-```
-
 ## Stop on failure
 
 Follow [cli-failures.md](../../ai-spector/references/cli-failures.md). Do not hand-edit `traceability.graph.json` to "fix" validate errors.

package/scaffold/cursor/skills/ai-spector-graph/references/validate-graph.md

@@ -8,12 +8,20 @@ Gate before generation. **User runs this command;** agent runs the CLI.
 
 ## Required Behavior
 
+**MCP (preferred when ai-spector server is configured):**
+
+```
+graph_validate({})
+```
+
+**CLI fallback:**
+
 ```bash
 npx ai-spector graph validate
 ```
 
-- **Exit 0** → tell the user OK; if domain nodes exist, suggest `/generate-srs`; if only section shells, explain they need `/analyze` first.
-- **Non-zero** → **stop**. Use [cli-failures.md](../../ai-spector/references/cli-failures.md): paste every `[ERROR]` line, explain each, give fix steps (usually re-run `/analyze` or fix one node then re-validate).
+- **Success / exit 0** → tell the user OK; if domain nodes exist, suggest `/generate-srs`; if only section shells, explain they need `/analyze` first.
+- **Failure / non-zero** → **stop**. Use [cli-failures.md](../../ai-spector/references/cli-failures.md): paste every `[ERROR]` line, explain each, give fix steps (usually re-run `/analyze` or fix one node then re-validate).
 
 **Do not:** guess validation in the agent, hand-fix the whole graph without showing the user, or proceed to `/generate-srs`.