@typeship-ax/mcp 0.9.1 → 0.19.0

package/AGENTS.md

@@ -1,9 +1,9 @@
 # typeship — agent context
 
-This package contains the generated MCP server for **typeship** (API v1.0.0, package v0.9.1).
+This package contains the generated MCP server for **typeship** (API v1.0.0, package v0.19.0).
 
 Resolve an OpenAPI or GraphQL Definition, diagnose it, and keep every
-selected SDK, CLI, and MCP Target current.
+selected CLI, MCP, and SDK Target current.
 
 Every operation but one requires a bearer credential: an organization
 API key from the console, or an OAuth access token carrying the operation's
@@ -12,9 +12,14 @@ consent. OAuth grants cannot switch organizations after consent. A browser
 session is not a credential for this API. The exception is POST /generate,
 which works anonymously with the free plan's limits.
 
+Examples use Parcel, a fictional delivery service. Replace its domains,
+repository names, and resource identifiers with your own. The hosted
+petstore Definition is a runnable sample.
+
 ## Ground rules
-- Typeship owns the files it generates. Change the API definition, generation settings, or definition patches, then regenerate those files. Repository delivery preserves files outside its generated-file ownership manifest; preserving a file does not add it to the package's exports, build, or tests.
-- Zero runtime dependencies; the program runs on Node.js 18+ and platform `fetch`.
+- Maintaining this package: when its repository receives reviewed regeneration pull requests, committed customizations are preserved and edits that overlap a generated change stop for review. Regenerating into a directory replaces its files.
+- A custom file ships only when the package manifest, exports, build, and tests include it. Add a package check for every custom build or test step.
+- Zero runtime dependencies; the program runs on Node.js 20+ and platform `fetch`.
 - `api.md` is the tool and schema reference; `api.json` is the machine-readable operation, schema, safety, and example contract. Read them before guessing.
 - Start with the local build or installation instructions in `README.md`. Generation does not publish a registry package.
 
@@ -22,6 +27,7 @@ which works anonymously with the free plan's limits.
 - Bearer token: set the `TYPESHIP_TOKEN` environment variable.
 
 ## MCP server
+- Use the README's MCP connection instructions. MCP `2025-11-25` and `2026-07-28` are selected automatically; no client protocol flags are required.
 - Build the package and configure your MCP client to run `node` with the absolute path to `dist/mcp.js`. After publishing, you can use `npx -y --package @typeship-ax/mcp typeship-mcp`. Set the package's auth environment variables in that client; `--read-only` prevents write tools.
 - This package exposes the compact `search_docs`, `read_docs`, and `execute` surface. Find an operation, read its complete contract, then call `execute` with its name and `arguments`; destructive operations return `CONFIRMATION_REQUIRED` until repeated with `confirm: true`. Operation names are not directly callable tools in this mode.
 - Tool arguments are checked against the schema before any request (unknown or mistyped arguments are one `isError` result with per-argument issues); pass `fields` (dotted paths) to keep only the result keys you need; errors carry `code` and `next_steps`.

package/README.md

@@ -2,9 +2,9 @@
 
 MCP server for typeship. [API reference](./api.md)
 
-Generated from the OpenAPI spec by [typeship](https://typeship.dev). Change the spec or generation settings, then regenerate; generated files are not hand-edited.
+Generated from the OpenAPI spec by [typeship](https://typeship.dev).
 
-- **Zero runtime dependencies** — built on the platform `fetch` in Node 18+
+- **Zero runtime dependencies** — built on the platform `fetch` in Node 20+
 - **Agent-ready MCP** — schema-derived tools, argument validation, read-only mode, and bounded results
 
 ## Build from source
@@ -16,7 +16,7 @@ npm install
 npm run build
 ```
 
-Requires Node.js 18+. The package is ESM.
+Requires Node.js 20+. The package is ESM.
 
 To run the local MCP server, configure your MCP client with `node` and the absolute path to `dist/mcp.js`, as shown below. The server communicates over stdio.
 
@@ -25,16 +25,20 @@ To run the local MCP server, configure your MCP client with `node` and the absol
 Generation does not publish a package. Before using the registry command below, confirm `name` and `version` in `package.json`, publish under a name you control, and verify that release is available on npm.
 
 ```sh
-npm install --global @typeship-ax/mcp@0.9.1
+npm install --global @typeship-ax/mcp@0.19.0
 ```
 
+## MCP client requirements
+
+Connect with your client's default settings. This server supports MCP `2025-11-25` and `2026-07-28` automatically; no protocol environment variables are required. After registering it, run `claude mcp list` to verify a Claude Code connection.
+
 ## Connect after publishing
 
 The npm connections below require `@typeship-ax/mcp` to be published under your package identity. To use downloaded source before publishing, use the local configuration in the next section. Hosted connections require a deployed server.
 
 Authentication: provide `TYPESHIP_TOKEN` through the MCP client's environment or secret settings. Keep credential values out of URLs and command arguments.
 
-> **Cursor:** Cursor 3.2 is not supported: it opens with the legacy initialize handshake, while this server speaks MCP 2026-07-28.
+For Cursor, merge a local or remote server entry from this README into `mcpServers` in `.cursor/mcp.json`, then enable the server in Cursor’s MCP settings.
 
 ### Local
 
@@ -82,6 +86,13 @@ A zero-dependency stdio server exposing a compact discovery surface: `search_doc
 
 Replace the path with the absolute path to this package's built `dist/mcp.js`.
 
+For Claude Code, you can register the local build from the shell configured above:
+
+```sh
+claude mcp add --transport stdio typeship -- node /absolute/path/to/package/dist/mcp.js
+claude mcp list
+```
+
 Replace the credential placeholder using the MCP client's secret storage when it has one. The local server reads `TYPESHIP_TOKEN` from its environment; credentials never belong in command arguments. If you also generated the CLI, its `typeship login` command stores credentials the local MCP server can reuse.
 
 Tool input schemas are derived from the OpenAPI spec, so agents see real parameter types and required fields. Arguments are checked before anything reaches the API (unknown or mistyped ones come back as one `isError` result, nothing is dropped), every tool takes `fields` to keep only the result keys it needs, and errors carry a stable `code` and `next_steps`.