@specset/cli 0.3.1 → 0.5.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@specset/cli",
-  "version": "0.3.1",
+  "version": "0.5.0",
   "description": "Command-line interface for Specset — authenticate, run GraphQL queries, and chat with Specset project agents.",
   "license": "Apache-2.0",
   "homepage": "https://specset.com",

package/skills/specset/SKILL.md

@@ -17,6 +17,7 @@ This is the core skill — setup and mechanics only. Domain workflows live in si
 | Skill | Use for |
 |---|---|
 | `specset-search` | Finding anything across specs, drawings, submittals, RFIs, documents, and closeout records |
+| `specset-tools` | Calling Specset's own retrieval tools directly (`specset tools`, `specset mcp`) — deeper than search, lighter than the in-app agent |
 | `specset-projects` | Creating projects, uploading spec/drawing PDFs, publishing spec and drawing sets |
 | `specset-submittals` | Submittal lifecycle, attachments, approvers, and AI compliance reviews |
 | `specset-rfis` | RFI logging, tracking, and responses |
@@ -123,6 +124,20 @@ specset api --query '{ __type(name: "CreateSubmittalInput") { inputFields { name
 
 The domain skills document the operations that matter for each workflow, but they are not exhaustive — when an operation or argument doesn't match, introspect rather than guess.
 
+## Agent Tools and MCP
+
+Beyond raw GraphQL, the CLI exposes Specset's own retrieval tools — semantic and keyword search over specs, drawings, submittals, RFIs, documents (plus closeout and schedule where enabled) — for an AI agent to call directly. Reach for these when you want the actual content to reason over, not just record previews.
+
+- **As commands:** `specset tools list` to see what's available, then `specset tools run <name> --input '{...}'` (or `-F key=value`).
+- **As a native MCP server:** `specset mcp` runs a stdio MCP server that surfaces these tools to an MCP client, reusing your CLI login, org, and host. Register it once:
+
+```bash
+claude mcp add specset -- specset mcp      # Claude Code
+codex mcp add specset -- specset mcp       # Codex
+```
+
+See the `specset-tools` skill for the full workflow — project scoping, the `-F` JSON-parsing difference, and the `sb://` citation convention.
+
 ## Uploading Files
 
 Several workflows attach an uploaded file — submittal PDFs, RFI attachments, project documents, org logos. Files are uploaded directly to storage via a presigned URL, so attaching one is a three-step flow that needs `bash`, `curl`, and `jq`. The result is a **file id** you pass to whatever mutation consumes it.

package/skills/specset-search/SKILL.md

@@ -18,6 +18,8 @@ Remember Variable Limitations from the `specset` skill: `-F` sends **strings onl
 - **`quickSearch`** — fast flat matching against titles and identifiers; use when the user roughly knows the record's name or number.
 - **Precise lookups** — when the user already has a spec section number or drawing sheet number, skip search and fetch directly.
 
+> Need the actual content, not just previews and IDs? The `specset-tools` skill exposes Specset's own retrieval tools (`specset tools run searchSpecSections`, `searchDrawingSheets`, `searchDocuments`, …), which return expanded, citation-anchored markdown. Use `search`/`quickSearch` here to locate records cheaply; reach for `specset-tools` when you need to read and reason over the content.
+
 ## Unified Search: `search`
 
 ```graphql

package/skills/specset-tools/SKILL.md

@@ -0,0 +1,117 @@
+---
+name: specset-tools
+description: Use when an agent should call Specset's own retrieval tools directly — semantic/keyword search and structured reads over specs, drawings, submittals, RFIs, documents, closeout, and schedule — via `specset tools` or a `specset mcp` server. Deeper than raw GraphQL search; lighter than delegating to the in-app agent.
+allowed-tools: Bash Read AskUserQuestion
+---
+
+# Specset Agent Tools (`specset tools`, `specset mcp`)
+
+Requires the `specset` CLI, logged in with an active org. If a command fails with `command not found`, `Not logged in`, or `No active organization`, follow First-Run Setup in the `specset` skill.
+
+These are the same read-only retrieval tools Specset's own in-app agent uses — exposed so external agents can call them directly. Everything here is read-only; nothing needs user confirmation.
+
+## When to use which surface
+
+There are three tiers of Specset retrieval. Pick the lightest one that answers the question:
+
+1. **Typed GraphQL search** (`specset-search` skill: `search`, `quickSearch`, `specSectionByNumber`, …) — cheapest, returns previews and IDs. Best for "does X exist / find the record."
+2. **Agent tools** (this skill) — the middle tier. `searchSpecSections` / `searchDrawingSheets` / `searchDocuments` return expanded, citation-anchored markdown (the real retrieval), and the `get*Content` tools read full sections. Best when you need the actual content to reason over.
+3. **In-app agent** (`specset-agent` skill: `specset agent chat`) — heaviest. Delegates the whole question to Specset's agent, which reasons and synthesizes. Best when the answer needs cross-document judgment, not just retrieval.
+
+## Listing tools
+
+```bash
+specset tools list
+specset tools list --project <projectId|sb://project/...>
+specset tools list --json     # full input schemas
+```
+
+The listing includes usage guidance and marks project-scoped tools. The exact set depends on the org (closeout and schedule tools require their SKUs) and on whether a project is in scope.
+
+## Running a tool
+
+Provide input as a JSON object (`--input`) or as repeated `-F key=value` fields. **Unlike `specset api -F` (strings only), `specset tools run -F` JSON-parses each value**, so numbers, booleans, and lists work:
+
+```bash
+# JSON input
+specset tools run searchSpecSections \
+  --project <projectId> \
+  --input '{"query": "concrete curing requirements"}'
+
+# Field form (values are JSON-parsed, string fallback)
+specset tools run searchSpecSections --project <projectId> \
+  -F query="fire rating" -F keywords='["ASTM E119"]' -F limit=5
+
+# Read a specific section's full content using an ID from a search result
+specset tools run getSpecSectionContent -F id='sb://spec/....'
+```
+
+Output is the tool's JSON payload (`{ success, message?, result? }`); a `{ success: false }` payload exits non-zero.
+
+### Identifiers are citation IDs, not links
+
+Tool results embed identifiers shaped like `sb://spec/<uuid>` or `sb://drawing/<uuid>`. Pass them back into other tools verbatim (e.g. into `getSpecSectionContent`, `getDrawingSheet`). They are **not** web URLs — don't present them to a person as clickable links.
+
+### Project scoping
+
+Most tools are project-scoped. Either pass `--project` (a UUID or `sb://project/...`), or include `projectId` in the tool input. Use `listProjects` to discover project IDs. With `--project` set, per-call `projectId` becomes optional.
+
+## Downloading source files (drawings, documents, specs, submittals, RFIs)
+
+The retrieval tools return **extracted text**, which is authoritative for schedules, notes, and spec paragraphs — but cannot answer spatial/visual questions (routing, clearances, what a plan view actually shows) and never carries the original file. Every entity has a download command, and **each accepts its `sb://` citation URL verbatim** (as returned by issues, search, and tool results — any `#page=`/`#nodeId=` fragment is ignored) or a bare UUID:
+
+```bash
+# Drawing sheets — image (rendered PNG, default), pdf (single-sheet), file (whole set).
+# Also accepts a sheet number with --project. Read the PNG with vision to inspect geometry.
+specset drawings download 'sb://drawing/<uuid>#nodeId=d1' --out /tmp/sheets/
+specset drawings download E308 --project <projectId> --format pdf
+
+# Project documents — also covers RFI attachments and closeout documents,
+# which all reference a document:
+specset docs download 'sb://doc/<uuid>'
+
+# Spec sections — per-section PDF slice (default) or the whole source spec file.
+# Also accepts a section number with --project:
+specset specs download '23 31 19' --project <projectId>
+specset specs download 'sb://spec/<uuid>' --asset book
+
+# Submittals — compiled package (default when present), cover sheet, or attachments.
+# --list shows the asset inventory first:
+specset submittals download 'sb://sub/<uuid>' --list
+specset submittals download 'sb://sub/<uuid>' --asset attachment --index 2
+specset submittals download 'sb://sub/<uuid>' --asset attachment --all --out ./sub-42/
+
+# RFIs — question + response attachments:
+specset rfis download 'sb://rfi/<uuid>' --list
+specset rfis download 'sb://rfi/<uuid>' --all --out ./rfi-7/
+
+# Raw file resources — the escape hatch when you already hold an sb://file id:
+specset files download 'sb://file/<uuid>'
+```
+
+All commands support `--json` (structured `{files: [{path, bytes, ...}]}` output) and `--out` (file path, or directory for multi-file downloads). A citation passed to the wrong command errors with the right one to use.
+
+Typical loop for drawings: search or `getDrawingSheetContent` to find the sheet → hit a visual question the text can't settle → `drawings download` → **read the PNG with your vision/file-reading tool**.
+
+## MCP server (Claude Code, Codex, other MCP clients)
+
+`specset mcp` runs a stdio MCP server that exposes these tools natively, reusing your CLI login, org, and host config. Register it once and the client can call the tools directly:
+
+```bash
+# Claude Code
+claude mcp add specset -- specset mcp
+# Optionally pin a project and/or host:
+claude mcp add specset -- specset mcp --project <projectId> --host https://app.specbook.ai
+
+# Codex
+codex mcp add specset -- specset mcp
+```
+
+Notes:
+- The server writes only the MCP protocol to stdout; diagnostics go to stderr.
+- Scope (org, optional project, host) is fixed for the life of the server — restart it to change scope.
+- If the session expires mid-run, tool calls return an actionable error; run `specset login` and restart the server.
+
+## Stability
+
+This surface is experimental — tool names and input schemas may change. For automation you need to keep stable, prefer the typed `search` / `quickSearch` GraphQL queries in the `specset-search` skill.