@typeship-ax/mcp 0.21.0 → 0.22.0

package/AGENTS.md

@@ -1,6 +1,6 @@
-# typeship — agent context
+# Typeship: agent guide
 
-This package contains the generated MCP server for **typeship** (API v1.0.0, package v0.21.0).
+Instructions for coding agents that call the Typeship API through this MCP server (API version 1.0.0, package version 0.22.0).
 
 Resolve an OpenAPI or GraphQL Spec, diagnose it, and keep every
 selected CLI, MCP, and SDK Target current.
@@ -16,22 +16,26 @@ Examples use Parcel, a fictional delivery service. Replace its domains,
 repository names, and resource identifiers with your own. The hosted
 petstore Spec is a runnable sample.
 
-## Ground rules
-- 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.
+## Before writing code
+- `api.md` is the tool and schema reference; `api.json` is the machine-readable contract: every operation's inputs, outputs, errors, `safety` (`read`, `write`, or `destructive`), and an example. Look up exact names there instead of guessing.
+- `README.md` covers installation and setup.
 - 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.
 
 ## Authentication
 - 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.
+- `README.md` shows how to connect an MCP client. The server supports MCP `2025-11-25` and `2026-07-28` and picks the version automatically; clients need no protocol flags.
+- Clients start the server with `npx -y --package @typeship-ax/mcp typeship-mcp`. Set the auth environment variables in the client's configuration; `--read-only` removes write tools.
+- This package exposes the compact `search_docs`, `read_docs`, and `execute` surface. Find an operation, read its arguments and example with `read_docs`, 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`.
 
+## Safety
+- Read credentials from the environment or a secret store. Never hard-code them, print them, or put them in URLs or command arguments.
+- Check an operation's `safety` in `api.json` before calling it. Confirm with the user before running a `write` or `destructive` operation they did not ask for.
+- For exploration or reporting, run the MCP server with `--read-only` so no tool can write.
+- Keep results small: select only the fields you need with `fields` (MCP).
+
 ## Documentation
 - The reference for this exact package: `api.md` (offline, always current with the code).
-- Conceptual guides live on the docs site. For questions about how the API's concepts fit together (flows, ordering, environments), fetch `https://typeship.dev/llms-full.txt` and read the relevant sections; `https://typeship.dev/llms.txt` is the page index. Relative links in the spec resolve against `https://typeship.dev`.
+- Conceptual guides live on the docs site. For questions about how the API's concepts fit together (flows, ordering, environments), fetch `https://typeship.dev/llms-full.txt` and read the relevant sections; `https://typeship.dev/llms.txt` is the page index. Relative links in the spec resolve against `https://typeship.dev/docs`.

package/README.md

@@ -1,44 +1,22 @@
 # @typeship-ax/mcp
 
-MCP server for typeship. [API reference](./api.md)
+MCP server for the Typeship API. [API reference](./api.md)
 
-Generated from the OpenAPI spec by [typeship](https://typeship.dev).
+Resolve an OpenAPI or GraphQL Spec, diagnose it, and keep every selected CLI, MCP, and SDK Target current.
 
-- **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
+## Installation
 
-## Build from source
-
-Run these commands in the downloaded or cloned package directory:
+MCP clients start the server with `npx`, so it needs no separate installation (see [Connect an MCP client](#connect-an-mcp-client)). To install the `typeship-mcp` command globally instead:
 
 ```sh
-npm install
-npm run build
+npm install --global @typeship-ax/mcp@0.22.0
 ```
 
-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.
-
-## Install a published package
-
-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.21.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.
+Requires Node.js 20+.
 
-## Connect after publishing
+## Connect an MCP client
 
-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.
-
-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.
+Provide `TYPESHIP_TOKEN` through the MCP client's environment or secret settings. Keep credential values out of URLs and command arguments.
 
 ### Local
 
@@ -64,17 +42,20 @@ For Cursor, merge a local or remote server entry from this README into `mcpServe
 - Codex: `codex mcp add typeship-readonly --url https://typeship.dev/mcp/readonly`
 - [Install in VS Code](vscode:mcp/install?%7B%22name%22%3A%22typeship-readonly%22%2C%22type%22%3A%22http%22%2C%22url%22%3A%22https%3A%2F%2Ftypeship.dev%2Fmcp%2Freadonly%22%7D)
 
-## MCP server
+### Other clients
 
-A zero-dependency stdio server exposing a compact discovery surface: `search_docs`, `read_docs`, and `execute`. Read an operation before executing it to get its complete schema, example arguments, and safety classification. After building, add the local server to an MCP client:
+Add a server entry to your client's MCP configuration. For Cursor, merge it into `mcpServers` in `.cursor/mcp.json`, then enable the server in Cursor's MCP settings:
 
 ```json
 {
   "mcpServers": {
     "typeship": {
-      "command": "node",
+      "command": "npx",
       "args": [
-        "/absolute/path/to/package/dist/mcp.js"
+        "-y",
+        "--package",
+        "@typeship-ax/mcp",
+        "typeship-mcp"
       ],
       "env": {
         "TYPESHIP_TOKEN": "replace-with-your-credential"
@@ -84,28 +65,16 @@ 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.
+Replace the credential placeholder using the MCP client's secret storage when it has one. The server reads `TYPESHIP_TOKEN` from its environment; credentials never belong in command arguments.
 
-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`.
+The server supports MCP `2025-11-25` and `2026-07-28` and picks the version automatically, so clients need no protocol settings. After registering it with Claude Code, `claude mcp list` shows the connection.
 
-Add `--read-only` to `args` (or set `TYPESHIP_MCP_READ_ONLY=1`) for a server that cannot write, `--tools generate,projects` (or `TYPESHIP_MCP_TOOLS`) to expose a subset, and `TYPESHIP_MCP_MAX_RESULT_CHARS` to change the result size cap (64,000).
+## Tools
 
-## MCP Registry
+The server runs over stdio with no runtime dependencies and exposes a compact discovery surface: `search_docs`, `read_docs`, and `execute`. Read an operation before executing it to get its arguments, an example, and its safety classification.
 
-`server.json` describes the npm executable and any hosted transports. Its `dev.typeship/typeship` identity matches `package.json#mcpName`.
+Tool input schemas come 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`.
 
-Install the official `mcp-publisher`, publish this npm package first, then validate or publish the listing:
+Add `--read-only` to `args` (or set `TYPESHIP_MCP_READ_ONLY=1`) for a server that cannot write, `--tools projects,specs` (or `TYPESHIP_MCP_TOOLS`) to expose a subset, and `TYPESHIP_MCP_MAX_RESULT_CHARS` to change the result size cap (64,000).
 
-```bash
-npm run mcp:validate
-npm run mcp:publish
-```
+Generated from the OpenAPI spec by [Typeship](https://typeship.dev).