@myspec/mcp-server 0.1.0-next.1

package/README.md

@@ -0,0 +1,154 @@
+# @myspec/mcp-server
+
+MCP server for the MySpec platform. Exposes projects, files, and attachments to MCP-aware clients (Claude Desktop, Claude Code, Cursor) over stdio.
+
+## Install & run
+
+```bash
+# One-shot via npx
+npx -y @myspec/mcp-server login           # browser-based OAuth sign-in
+npx -y @myspec/mcp-server                 # start the MCP server (stdio)
+```
+
+You can add the server to your MCP client before logging in — it will start up and connect successfully, and each tool call will return an error result prompting you to run `npx @myspec/mcp-server login`. Once you sign in, tools work immediately without restarting the MCP client.
+
+## CLI
+
+Run with `npx @myspec/mcp-server [command]` (or `myspec-mcp [command]` when installed on your PATH):
+
+```text
+(default)                 Start MCP server over stdio
+serve                     Start MCP server over stdio
+login                     Sign in via browser loopback OAuth
+login --paste             Sign in by pasting a one-time code
+login --provider <google|github|gitlab|linear|atlassian>
+logout                    Revoke refresh token and clear local credentials
+```
+
+Credentials are persisted at `$XDG_CONFIG_HOME/myspec/mcp-server.json` (POSIX) or `%APPDATA%\myspec\mcp-server.json` (Windows), mode `0600`.
+
+## Environment variables
+
+| Variable | Purpose |
+|---|---|
+| `MYSPEC_USER_AUTH_URL` | user-auth base URL (default `https://auth.myspec.dev`) |
+| `MYSPEC_PLATFORM_URL` | platform API base URL (default `https://api.myspec.dev`) |
+| `MYSPEC_REFRESH_TOKEN` | Skip file-based credentials; the server mints a fresh access token on first use via this refresh token. The supported way to wire the MCP server up without running `npx @myspec/mcp-server login`. |
+| `MYSPEC_DOWNLOAD_ROOT` | Absolute path used by `read_file` as its on-disk cache root (default: `~/.myspec`). Tools never write outside this root. |
+| `MYSPEC_WEBAPP_URL` | Webapp base URL used by `login --paste` to display the OAuth callback URL (default: derived from `MYSPEC_USER_AUTH_URL`) |
+
+## Tools
+
+| Name | Inputs | Output |
+|---|---|---|
+| `list_projects` | `query?`, `limit?`, `offset?` | Paginated list of projects |
+| `get_project` | `project_id` | Project + active sessions + files + attachments |
+| `get_file` | `file_id`, optional `include_download_url` | File metadata; with `include_download_url=N` also returns a download URL targeting revision `N` |
+| `read_file` | `file_id`, optional `revision` | UTF-8 content of the file (errors for binary). Cached on disk under `MYSPEC_DOWNLOAD_ROOT` |
+| `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, ...) |
+
+### `include_download_url` semantics
+
+`get_file`:
+
+- Omit or `0` → metadata only.
+- Equal to current `revision_count` → adds `download_url` (signed) and `expires_at`.
+- Less than `revision_count` → adds `download_url` pointing at `${platform}/project/v1/files/{id}/revisions/{N}`, `download_headers: ["Authorization: Bearer <access_token>"]`, and `expires_at` (the access token's expiry). Signed URLs are not available for historical revisions, so the consumer must send those headers. **Treat the response as sensitive — the token is short-lived but still a credential.**
+- Greater than `revision_count` → tool error.
+
+`get_attachment`:
+
+- Omit or `0` → metadata only.
+- Any positive integer → adds a signed `download_url` and `expires_at`. Attachments do not have revisions, so the integer value is just an on/off flag.
+
+## Claude Desktop config snippet
+
+```json
+{
+  "mcpServers": {
+    "myspec": {
+      "command": "npx",
+      "args": ["-y", "@myspec/mcp-server"]
+    }
+  }
+}
+```
+
+## Development
+
+```bash
+cd projects/mcp-server
+npm install
+npm run typecheck
+npm run lint
+npm run test            # unit tests (vitest)
+npm run build           # emits dist/index.js (Node 18+ ESM, bundled, with shebang)
+npm run test:integration  # builds dist + runs test/integration against mock servers
+node dist/index.js login
+```
+
+## Releasing & publishing
+
+This package is published to npm as `@myspec/mcp-server` by GitHub Actions.
+Prereleases are automatic on merge to `main`
+(`.github/workflows/mcp-server-push-main.yml`); the official `latest` release
+is a separate manual workflow (`.github/workflows/mcp-server-release.yml`). The
+published tarball is self-contained: `tsup` bundles the `@myspec/*` workspace
+packages into `dist/index.js`, so they live in `devDependencies` and are not
+installed by consumers.
+
+### One-time setup
+
+1. Ensure the `@myspec` scope exists on npm and your account can publish to it.
+2. Create an npm **granular access token** with publish rights to the `@myspec`
+   scope and add it to the repo as the **`NPM_TOKEN`** secret
+   (Settings → Secrets and variables → Actions).
+
+### Release flow
+
+- **Every PR to `main`** runs `mcp-server-pr-main.yml`: lint, typecheck, unit
+  tests, build, integration tests, a tarball smoke test, and `npm publish
+  --dry-run`. Nothing is uploaded.
+- **Every merge to `main`** runs `mcp-server-push-main.yml`, which
+  auto-publishes a prerelease `<version>-next.<run_number>` under the `next`
+  dist-tag (`npx @myspec/mcp-server@next`). The build fails if the base version
+  in `package.json` is already released — bump it first.
+- **Cutting a real release** is manual and separate: run the
+  `mcp-server-release` workflow via **Actions → Run workflow**
+  (`workflow_dispatch`). It publishes the clean `package.json` version to the
+  `latest` dist-tag. It rejects prerelease versions and refuses to republish an
+  existing version. A `dry_run` input is available to validate without
+  uploading.
+
+### Bumping the version
+
+The version lives in `projects/mcp-server/package.json`. To bump it manually
+(e.g. to choose the next release version), from `projects/mcp-server`:
+
+```bash
+npm version patch --no-git-tag-version   # 0.1.0 -> 0.1.1 (also updates the lockfile)
+npm version minor --no-git-tag-version   # 0.1.0 -> 0.2.0
+npm version major --no-git-tag-version   # 0.1.0 -> 1.0.0
+```
+
+`--no-git-tag-version` edits `package.json` + `package-lock.json` only (no git
+commit or tag). `main` is protected, so commit the bump on a branch and open a
+PR.
+
+**This is automated after a release.** The `mcp-server-release` workflow has a
+`next_bump` input (`patch` by default; `minor`/`major` selectable). After a
+successful publish to `@latest`, its `bump-next` job opens a PR bumping
+`package.json` to the next version — so you normally don't bump by hand. Merge
+that PR and `main` is ready for the next cycle. (The job uses the
+`GOSU_GITHUB_TOKEN` PAT so the bump PR triggers CI and can be merged.)
+
+### Conventions & gotchas
+
+- **`package.json` always holds the next *unreleased* version.** After
+  releasing `0.2.0`, bump to `0.3.0` so prereleases on `main` stay ahead of
+  `@latest`. The post-release `bump-next` job does this for you.
+- **`npx @myspec/mcp-server` (no tag) only resolves once a `latest` exists** —
+  run the manual release at least once. Until then, only `@next` is available.
+- The `version` reported by `myspec-mcp --version` is read from `package.json`
+  at runtime, so it always matches the published version.