@myspec/mcp-server 0.3.0 → 0.4.0-next.100

package/README.md

@@ -101,9 +101,17 @@ claude mcp add --scope user myspec \
 ```
 
 Nothing else is required — no `login`, no files. **For a non-production token,
-set `MYSPEC_USER_AUTH_URL` too** (e.g. `https://dev-auth.myspec.dev`); a dev
-token against the production default fails with a bare 401 that reads like a bad
-token.
+set `MYSPEC_USER_AUTH_URL` too** (e.g. `https://dev-auth.myspec.dev`) unless
+`~/.myspec/settings.json` already names that environment, which the server reads
+even with no `oauth_creds.json` beside it; a dev token against the production
+default fails with a 401 that reads like a bad token until you read the host it
+names.
+
+That cuts both ways: set it explicitly for a **production** token on a machine
+that was ever signed in to dev. `login` writes `settings.json` and `logout` does
+not remove it, so the leftover `userAuthUrl` decides the exchange either way.
+The 401 names the host it asked, so the wrong environment is visible rather than
+looking like a rejected token.
 
 The server writes `~/.myspec/settings.json` so restarts skip endpoint discovery.
 It never writes the token to disk, so unsetting the variable removes the
@@ -272,7 +280,7 @@ Local state is stored under `~/.myspec/` (alongside the on-disk cache root), spl
 | Variable | Purpose |
 |---|---|
 | `MYSPEC_API_TOKEN` | Long-lived MySpec API token (`msp_pat_…`) for unattended use. Takes precedence over anything in `~/.myspec/oauth_creds.json` and is never written to disk. Needs 0.3.0+. |
-| `MYSPEC_USER_AUTH_URL` | user-auth base URL (default `https://auth.myspec.dev`). The webapp URL is derived from it; the platform / ai-agent URLs are discovered via the webapp. |
+| `MYSPEC_USER_AUTH_URL` | user-auth base URL (`--user-auth-url` > this > `userAuthUrl` in `~/.myspec/settings.json` > `https://auth.myspec.dev`). The webapp URL is derived from it; the platform / ai-agent URLs are discovered via the webapp. |
 | `MYSPEC_DOWNLOAD_ROOT` | Absolute path used by `read_spec_file` as its on-disk cache root (default: `~/.myspec`). Tools never write outside this root. |
 | `MYSPEC_AI_AGENT_WS_URL` | ai-agent WebSocket URL for `reverse`; skips the webapp discovery call |
 
@@ -290,6 +298,14 @@ Local state is stored under `~/.myspec/` (alongside the on-disk cache root), spl
 | `restore_spec_file_from_trash` | `file_id` | Restores a trashed spec file back to the active file list, reversing `move_spec_file_to_trash` |
 | `get_attachment` | `attachment_id`, optional `include_download_url` | Attachment metadata (looked up org-scoped by id); with `include_download_url>0` also returns a signed download URL |
 | `upload_attachment` | `project_id`, `file_path` (absolute), optional `file_name`, optional `mime_type`, optional `override` | Uploads the local file as a new attachment on the project. Returns `attachment_id`, `file_name` (the **effective** name the platform stored — may differ from the requested one when auto-dedup adds a `(N)` suffix), `has_file_name_conflict` (`true` when stored name ≠ requested name), `mime_type`, `file_size_bytes`, `checksum` (format: `sha256:<hex>`), `file_uri`, `reused_existing_attachment` (`true` when an existing attachment with the same name AND same checksum was found and returned without re-uploading; `file_uri` is then omitted because the list endpoint does not surface it — call `get_attachment` for a download URL). With `override=true`, any existing attachment whose recorded name matches is soft-deleted first (returned as `overridden_attachment_ids` — empty array means nothing matched) and the new upload keeps the requested name; the same-checksum short-circuit still applies, so a no-op re-upload never deletes anything. Max 10 MB. Supported content: PDF, DOCX, XLSX, and any UTF-8 text file (XML, JSON, YAML, HTML, Markdown, CSV, source code, ...) |
+| `list_attachments` | `project_id`, optional `limit`, optional `offset` | Paginated attachment metadata (`id`, `name`, `mime_type`, `file_size_bytes`, `checksum`, `created_at`) — `file_size_bytes` is always present so a caller can size-check before `read_attachment`. Default 50 per page, capped at 200; returns `total` and `next_offset` while records remain |
+| `read_attachment` | `attachment_id`, optional `offset`, optional `limit` | The attachment's content inline. UTF-8 text is paginated by line (`offset` is 1-based, default/cap 2000 lines, 1 MiB per response) with `content`, `start_line`, `end_line`, `read_lines`, `total_lines`, `truncated`, `next_offset`. Images (PNG, JPEG, GIF, WEBP) are returned whole as an MCP image block (never paginated, up to 10 MiB). Other binary types (PDF, DOCX, XLSX, ...) error with a pointer to the webapp and to `get_attachment include_download_url` as the local alternative |
+| `list_spec_sessions` | `project_id`, optional `archive_filter` (`active`/`archived`/`all`), optional `status`, optional `query`, optional `limit`, optional `offset` | Paginated session metadata plus `session_summary` and `context_size_bytes` — never the context itself or the chat transcript. Default 10 per page, capped at 20 |
+| `get_spec_session` | `session_id`, optional `include_context` | Session metadata (status, counters, timestamps, `archived_at`), `session_summary`, `context_size_bytes` and `context_keys`. `include_context=true` returns the full context under a 1 MiB ceiling (above it the tool errors with the actual size). The chat transcript is never returned |
+| `rename_spec_session` | `session_id`, `session_summary` | Sets `context.sessionSummary` (max 500 chars) via read-merge-write, preserving every other context key; works on archived sessions; refuses when the context is not a JSON object. Returns `renamed`, `session_id`, `session_summary` |
+| `archive_spec_session` | `session_id` | Archives the session (idempotent — re-archiving keeps the original `archived_at`); the required confirmation step before `delete_spec_session` |
+| `unarchive_spec_session` | `session_id` | Returns an archived session to the active list |
+| `delete_spec_session` | `session_id` | Soft-deletes an ARCHIVED session. Refuses non-archived sessions with an archive-first error and never archives on the caller's behalf |
 
 ### Download destinations