@jinshuju/mcp 0.2.0 → 0.3.0

package/README.md

@@ -5,44 +5,51 @@ The tools are generated from the [open API v1 openapi.yaml](https://jinshuju.net
 
 Two ways to use it:
 
-- **Remote (HTTP)** — the official deployment, with OAuth sign-in; for claude.ai, Cursor, Windsurf and the like;
-- **Local (stdio)** — `npx -y @jinshuju/mcp`; for local clients such as Claude Code, sharing one sign-in with [@jinshuju/cli](https://github.com/jinshuju/cli).
+- **Remote (HTTP)** — the official deployment at `https://jinshuju.net/mcp`, with OAuth sign-in; for claude.ai, Claude Code, Cursor, Windsurf and the like;
+- **Local (stdio)** — `npx -y @jinshuju/mcp` with an access token; for clients that only run local servers.
 
 ## Remote use
 
-Server URL: `https://mcp.jinshuju.net/mcp` (until launch, the URL published at open.jinshuju.net/mcp is authoritative).
+Server URL: `https://jinshuju.net/mcp`
 
-| Client      | Setup                                                                                   |
-| ----------- | --------------------------------------------------------------------------------------- |
-| claude.ai   | Settings → Connectors → Add custom connector, enter the server URL, sign in to Jinshuju |
-| Claude Code | `claude mcp add jinshuju -s user --transport http https://mcp.jinshuju.net/mcp`         |
-| Cursor      | `{ "mcpServers": { "jinshuju": { "url": "https://mcp.jinshuju.net/mcp" } } }`           |
-| Windsurf    | Same as above, with the key `serverUrl`                                                 |
+| Client      | Setup                                                                                                                                     |
+| ----------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
+| claude.ai   | Settings → Connectors → Add custom connector, enter the server URL, sign in to Jinshuju                                                   |
+| Claude Code | `claude mcp add jinshuju -s user --transport http https://jinshuju.net/mcp`, then run `/mcp` in Claude Code and sign in to Jinshuju there |
+| Cursor      | `{ "mcpServers": { "jinshuju": { "url": "https://jinshuju.net/mcp" } } }`                                                                 |
+| Windsurf    | Same as above, with the key `serverUrl`                                                                                                   |
 
 Without OAuth (CI, scripts), send an access token directly: `--header "Authorization: Bearer YOUR_ACCESS_TOKEN"`, or add `headers` to the config.
 Create a personal access token under [Profile → API](https://next.jinshuju.net/profile/api), and an account access token under [System settings → Account API](https://next.jinshuju.net/system/api_licence).
 
 ## Local use (stdio)
 
-```bash
-# Sign in once (browser OAuth); the credential is stored in ~/.jinshuju/config.json and shared by the cli and mcp
-npx -y @jinshuju/cli auth login
+Pass an access token (created as above) in `JINSHUJU_ACCESS_TOKEN`:
 
+```bash
 # Claude Code
-claude mcp add jinshuju -s user -- npx -y @jinshuju/mcp
+claude mcp add jinshuju -s user -e JINSHUJU_ACCESS_TOKEN=your_token -- npx -y @jinshuju/mcp
 ```
 
-Or skip the sign-in and pass a token:
-
-```bash
-claude mcp add jinshuju -s user -e JINSHUJU_ACCESS_TOKEN=your_token -- npx -y @jinshuju/mcp
+Other clients:
+
+```json
+{
+  "mcpServers": {
+    "jinshuju": {
+      "command": "npx",
+      "args": ["-y", "@jinshuju/mcp"],
+      "env": { "JINSHUJU_ACCESS_TOKEN": "your_token" }
+    }
+  }
+}
 ```
 
 To check it works, ask the assistant to "list my Jinshuju forms".
 
 ## Tools
 
-60 tools with the same names as those documented for the [Jinshuju MCP Server](https://open.jinshuju.net/mcp), plus `get_schema`. Each tool maps to one operation in openapi.yaml; a few combine two operations:
+60 tools with the same names as those documented for the [Jinshuju MCP Server](https://open.jinshuju.net/mcp). Each tool maps to one operation in openapi.yaml; a few combine two operations:
 
 | Category            | Tools                                                                                                                                                                                                                               |
 | ------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
@@ -58,96 +65,23 @@ To check it works, ask the assistant to "list my Jinshuju forms".
 | Uploads             | upload_entry_attachment, upload_form_image, upload_import_file                                                                                                                                                                      |
 | Schemas             | get_schema (reads an openapi schema by name, e.g. FieldInput, TextFieldInput)                                                                                                                                                       |
 
-Differences from the tools documented at open.jinshuju.net/mcp:
-
-- Presigned uploads (`prepare_*_upload`) are not in openapi.yaml; the `upload_*` tools here upload directly (the file is passed as base64);
-- `update_entry` only updates partially (PATCH); there is no full replace;
-- Data structures such as field types are served by the `get_schema` tool and the `jinshuju://schemas/{name}` resource.
-
 The full tool → operation mapping is in `mcp.overlay.yaml` and `src/generated/meta.json`.
 
 **Size.** The full tools/list is about 39k tokens (o200k estimate; about 36k without outputSchema).
 It stays that size by not inlining large schemas: field definitions (52 types), form settings, themes and the like become a one-line pointer; unions that branch on type, such as table columns, keep only their common properties.
 The model reads them on demand with `get_schema("FieldInput")` / `get_schema("TextFieldInput")`.
 
-## Environment variables
-
-| Variable                          | Meaning                                                                                                                                                |
-| --------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| `JINSHUJU_ACCESS_TOKEN`           | Credential for stdio mode; when set, the config file is not read                                                                                       |
-| `JINSHUJU_CONFIG`                 | Config file path, default `~/.jinshuju/config.json`                                                                                                    |
-| `JINSHUJU_API_BASE_URL`           | API URL, default `https://jinshuju.net/api/v1`                                                                                                         |
-| `JINSHUJU_AUTH_HOST`              | Authorization server, default `https://account.jinshuju.net`                                                                                           |
-| `JINSHUJU_MCP_PUBLIC_URL`         | Public URL in HTTP mode (the resource in the OAuth metadata); a comma-separated list is chosen by the request's Host; empty infers it from the request |
-| `JINSHUJU_MCP_MAX_RESULT_CHARS`   | Maximum characters of one result, default 120000; longer results are truncated with a hint to page                                                     |
-| `JINSHUJU_MCP_TOKEN_CACHE_TTL_MS` | Token verification cache in HTTP mode, default 5 minutes                                                                                               |
-| `POSTHOG_API_KEY`                 | PostHog project token (`phc_…`); when set, HTTP mode reports MCP analytics, see below                                                                  |
-| `POSTHOG_HOST`                    | PostHog ingestion host, default `https://us.i.posthog.com`                                                                                             |
-| `JINSHUJU_MCP_COLLECT_INTENT`     | Whether the model writes the user's intent in each call (`context` argument → `$mcp_intent`), default `true`                                           |
-| `SENTRY_DSN`                      | Sentry project DSN; when set, the Workers entry reports exceptions, see below                                                                          |
-| `SENTRY_ENVIRONMENT`              | Sentry environment name, optional                                                                                                                      |
-| `PORT` / `HOST`                   | Where the Node entry listens, default 8787 / 0.0.0.0                                                                                                   |
-
-## Usage analytics (PostHog MCP analytics)
-
-With `POSTHOG_API_KEY` set, the HTTP deployment reports tool usage through [@posthog/mcp](https://posthog.com/docs/mcp-analytics), on the same terms as the built-in MCP at jinshuju.net/mcp:
-
-- Only `$mcp_initialize` (legacy handshake) and `$mcp_tool_call` are reported; `tools/list`, resources, `$identify` and `$exception` are not;
-- A tool call records the tool name, the argument names (`$mcp_input_keys`), the duration, whether it failed and the truncated error, **but not the argument values or the result**;
-- Every tool gets one more argument, `context`, where the model writes what the user wants to do (`$mcp_intent`); email addresses, phone numbers, IPs and card numbers in it are masked before sending.
-  With `JINSHUJU_MCP_COLLECT_INTENT=false` the argument is no longer advertised, and a client that still sends it gets no error;
-- `distinct_id` is the Jinshuju user id; `$session_id` is derived from a hash of the token (one session per token); the client name / version come from the handshake or each request's `_meta`.
-
-stdio (local) mode reports nothing.
-
-## Error monitoring (Sentry)
-
-The Workers entry (`src/worker.ts`) is wrapped with [@sentry/cloudflare](https://docs.sentry.io/platforms/javascript/guides/cloudflare/) and reports once `SENTRY_DSN` is set:
+## Environment variables (stdio)
 
-- It reports the unexpected: exceptions thrown by tool handlers (an unreachable API / timeout is a warning), the API being unreachable during token verification, and errors the routes did not catch. A 4xx / 5xx from the API is a normal tool result and is not reported;
-- No request bodies, IPs or cookies are collected, and tracing is off; sensitive request headers such as `Authorization` are scrubbed to `[Filtered]` by the SDK; the user is recorded only as the Jinshuju user id.
-
-The Node entry (Docker) and stdio report nothing.
+| Variable                        | Meaning                                                                                            |
+| ------------------------------- | -------------------------------------------------------------------------------------------------- |
+| `JINSHUJU_ACCESS_TOKEN`         | Access token (personal or account)                                                                 |
+| `JINSHUJU_API_BASE_URL`         | API URL, default `https://jinshuju.net/api/v1`                                                     |
+| `JINSHUJU_MCP_MAX_RESULT_CHARS` | Maximum characters of one result, default 120000; longer results are truncated with a hint to page |
 
 ## Development
 
-```bash
-npm install
-npm run generate     # spec/openapi.yaml + mcp.overlay.yaml -> src/generated/ (operations / tools / schemas / meta)
-npm run check        # typecheck + oxlint + oxfmt
-npm test             # builds, then runs node:test without touching the network
-npm run dev          # local HTTP server: http://127.0.0.1:8787/mcp
-npm run spec:update  # fetches the latest live openapi.yaml and regenerates
-```
-
-After changing `mcp.overlay.yaml` or updating `spec/openapi.yaml`, run `npm run generate` and commit `src/generated/`; CI checks it.
-
-## Deployment
-
-- **Docker (official)**: `docker build -t jinshuju-mcp . && docker run -p 8787:8787 -e JINSHUJU_MCP_PUBLIC_URL=https://mcp.jinshuju.net jinshuju-mcp`
-- **Cloudflare Workers (optional)**: `npx wrangler login && npm run worker:deploy`
-- **WDL or another Workers-compatible platform (optional)**: with [`@wdl-dev/cli`](https://github.com/wdl-dev/cli) installed and its token configured, `npm run wdl:deploy`;
-  set the public URL as the secret `JINSHUJU_MCP_PUBLIC_URL` (`wdl secret put --worker jinshuju-mcp JINSHUJU_MCP_PUBLIC_URL`),
-  with several entry points comma-separated, e.g. `https://mcp.jinshuju.net,https://<ns>.<platform>/jinshuju-mcp`;
-  to report to PostHog add the secret `POSTHOG_API_KEY` (and `POSTHOG_HOST` if needed); to report to Sentry add `SENTRY_DSN`.
-
-The service is stateless and needs no database, KV or Durable Objects.
-
-## Evals
-
-`evals/` is an automated, multi-model evaluation built from real usage: 42 tasks (categories 找表单 / 读数据 / 统计汇总 / 建表单 / 改设置 / 批量写入 / 导入 — find forms, read entries, aggregate, create forms, change settings, batch writes, import)
-run against both this repository's MCP and the built-in MCP (jinshuju.net/mcp), are scored by assertions, produce pass-rate and token tables by model × MCP × category,
-and write every run into a Jinshuju form. Usage, task format and metrics are in [evals/README.md](evals/README.md).
-
-```bash
-npm run eval -- seed     # prepares fixture data in the eval account
-npm run eval -- run      # all tasks × EVAL_MODELS × new,builtin → evals/results/<run_id>/report.md
-```
-
-## Design notes
-
-- [ARCHITECTURE.md](ARCHITECTURE.md) — modules, the path of one call, generation rules, authentication
-- [evals/README.md](evals/README.md) — the eval system: sample set, runner, scoring, persistence
+Building, running and deploying the server: [DEVELOPMENT.md](DEVELOPMENT.md). How it fits together: [ARCHITECTURE.md](ARCHITECTURE.md).
 
 ## License
 

package/dist/analytics.d.ts

@@ -2,10 +2,13 @@
  * PostHog MCP analytics (@posthog/mcp): the HTTP deployment reports how the tools are used. stdio runs on the user's
  * own machine and reports nothing.
  *
- * What is captured matches goldendata's built-in MCP (TrackMCPEventService):
+ * What is captured:
  * - only $mcp_initialize and $mcp_tool_call; tools/list, resources/*, $identify and $exception are all dropped;
  * - a tool call records only argument names ($mcp_input_keys), never argument values or the result; a failure records
- *   its category and the truncated error;
+ *   the truncated error text, its bucket ($mcp_error_type: validation / permission / timeout / rate_limited / api_4xx /
+ *   api_5xx / internal, read off the text because the SDK types only thrown exceptions and our tools return isError
+ *   results) and, for an API failure, the HTTP status ($mcp_error_status);
+ * - mcp_caller_type tells Jiri's remaining in-house path (client name mcp, python-httpx user agent) from everyone else (external);
  * - intent: every tool gets a context argument where the model says what the user wants to do ($mcp_intent). The SDK
  *   scrubs emails / phone numbers / IPs / card numbers from it before sending; JINSHUJU_MCP_COLLECT_INTENT=false turns
  *   it off entirely (the argument is no longer offered and nothing is reported);
@@ -21,9 +24,26 @@
  */
 import type { AuthInfo, McpServer } from '@modelcontextprotocol/server';
 import type { Config } from './config.js';
-/** Asks the model the same question as goldendata's built-in MCP, so $mcp_intent is comparable across the two. */
+/** The question the model answers in the context argument; it becomes $mcp_intent. */
 export declare const CONTEXT_DESCRIPTION = "Why are you calling this tool? Briefly describe the user's goal.";
 export declare const CONTEXT_INSTRUCTIONS: string;
+/** The buckets PostHog's own MCP analytics uses for $mcp_error_type, so its dashboards read our events directly. */
+export type ErrorType = 'validation' | 'permission' | 'timeout' | 'rate_limited' | 'api_4xx' | 'api_5xx' | 'internal';
+/**
+ * Buckets a failed tool call by its text, whose shapes are all ours: result.ts opens an API failure with `HTTP <status>:`
+ * and closes it with a hint, api.ts opens a TransportError with the reason, and the MCP SDK prefixes a validation failure.
+ * Anything else is an exception a tool threw, which is a bug of ours.
+ */
+export declare function classifyError(message: string): {
+    type: ErrorType;
+    status?: number;
+};
+/**
+ * Who is calling: `jiri` for the in-house assistant's remaining path through this server, which runs on the Python MCP
+ * SDK's defaults (client name mcp, python-httpx user agent) and nothing else does; `external` for everyone else. The
+ * retired built-in server reported the same two values.
+ */
+export declare function callerTypeOf(clientName: unknown, userAgent: unknown): 'jiri' | 'external';
 export interface AnalyticsOptions {
     /** PostHog project token (phc_…) */
     apiKey: string;

package/dist/analytics.js

@@ -1,9 +1,10 @@
 import { deriveSessionIdFromMCPSession, instrument } from '@posthog/mcp';
 import { PostHog } from 'posthog-node';
 import { sha256, userIdOf } from './auth.js';
+import { FORBIDDEN_HINT } from './result.js';
 import { TOOLS } from './tools.js';
 import { CONTEXT_ARGUMENT } from './validation.js';
-/** Asks the model the same question as goldendata's built-in MCP, so $mcp_intent is comparable across the two. */
+/** The question the model answers in the context argument; it becomes $mcp_intent. */
 export const CONTEXT_DESCRIPTION = "Why are you calling this tool? Briefly describe the user's goal.";
 export const CONTEXT_INSTRUCTIONS = `Every tool takes a \`${CONTEXT_ARGUMENT}\` argument: say what the user is actually trying to get done, ` +
     'in their own words, rather than restating what the tool does — it is what tells us which needs these tools ' +
@@ -24,6 +25,51 @@ const DECLARED_PARAMETER_NAMES = new Set([
     'name',
     ...TOOLS.flatMap((tool) => Object.keys(tool.inputSchema.properties ?? {}))
 ]);
+/**
+ * An argument problem caught before any request goes out: the MCP SDK's prefix on a validation.ts failure, get_schema's
+ * unknown name, a composite tool given nothing to send, a path parameter left empty; and validation.ts's own phrasings,
+ * should the SDK ever stop prefixing them.
+ */
+const VALIDATION_ERROR = /^(Input validation error|No schema named|Nothing to change|Missing path parameter|Unknown arguments)\b|Instance type|required property/;
+/**
+ * Buckets a failed tool call by its text, whose shapes are all ours: result.ts opens an API failure with `HTTP <status>:`
+ * and closes it with a hint, api.ts opens a TransportError with the reason, and the MCP SDK prefixes a validation failure.
+ * Anything else is an exception a tool threw, which is a bug of ours.
+ */
+export function classifyError(message) {
+    const http = /^HTTP (\d{3}):/.exec(message);
+    if (http) {
+        const status = Number(http[1]);
+        if (status === 429)
+            return { type: 'rate_limited', status };
+        if (status === 403 && /\bscope\b/i.test(serverErrorLines(message)))
+            return { type: 'permission', status };
+        return { type: status >= 500 ? 'api_5xx' : 'api_4xx', status };
+    }
+    if (VALIDATION_ERROR.test(message))
+        return { type: 'validation' };
+    if (/^Request timed out\b/.test(message))
+        return { type: 'timeout' };
+    return { type: 'internal' };
+}
+/** What the API itself said: the lines between result.ts's `HTTP <status>:` line and its hint (the 403 hint mentions scope itself). */
+function serverErrorLines(message) {
+    return message
+        .split('\n')
+        .slice(1)
+        .filter((line) => line !== FORBIDDEN_HINT && !line.startsWith('⚠'))
+        .join('\n');
+}
+/**
+ * Who is calling: `jiri` for the in-house assistant's remaining path through this server, which runs on the Python MCP
+ * SDK's defaults (client name mcp, python-httpx user agent) and nothing else does; `external` for everyone else. The
+ * retired built-in server reported the same two values.
+ */
+export function callerTypeOf(clientName, userAgent) {
+    return clientName === 'mcp' && typeof userAgent === 'string' && userAgent.startsWith('python-httpx/')
+        ? 'jiri'
+        : 'external';
+}
 /** Forwards the SDK's internal log to console only when something is wrong; drops the "Successfully set up…" every request prints. */
 function warn(message) {
     if (/^(Warning|Error|WARN)\b/.test(message))
@@ -64,7 +110,6 @@ export class McpAnalytics {
             enableConversationId: false,
             enableExceptionAutocapture: false,
             identify: distinctId ? { distinctId } : null,
-            eventProperties: () => ({ mcp_caller_type: 'external' }),
             shouldRecordInputKey: (key, { declared }) => declared || DECLARED_PARAMETER_NAMES.has(key),
             beforeSend: this.beforeSend(sessionId),
             logger: warn
@@ -96,6 +141,14 @@ export class McpAnalytics {
             }
             if (event.event === '$mcp_initialize' && this.repeatedHandshake(String(props.$session_id ?? '')))
                 return null;
+            if (event.event === '$mcp_tool_call' && props.$mcp_is_error === true) {
+                // The SDK types a thrown exception by its class; an isError result is always "Error", so the bucket comes from the text.
+                const { type, status } = classifyError(String(props.$mcp_error_message ?? ''));
+                props.$mcp_error_type = type;
+                if (status !== undefined)
+                    props.$mcp_error_status = status;
+            }
+            props.mcp_caller_type = callerTypeOf(props.$mcp_client_name, props.$mcp_client_user_agent);
             return event;
         };
     }

package/dist/api.js

@@ -21,11 +21,12 @@ export function buildUrl(baseUrl, op, args) {
         const value = args[p.name];
         if (value === undefined || value === null || value === '')
             continue;
-        if (Array.isArray(value)) {
+        if (Array.isArray(value) && !p.json) {
             for (const item of value)
                 url.searchParams.append(`${p.name}[]`, scalar(item));
         }
         else {
+            // A `content: application/json` parameter goes as one value: the array as JSON text, a string (JSON text already) as is
             url.searchParams.set(p.name, scalar(value));
         }
     }

package/dist/generated/meta.json

@@ -2,11 +2,11 @@
     "generatedFrom": {
         "title": "Jinshuju API v1",
         "version": "1.0",
-        "sha256": "54912d2240cc55de"
+        "sha256": "288548a94e3932e7"
     },
     "baseUrl": "https://jinshuju.net/api/v1",
     "toolCount": 60,
-    "operationCount": 123,
+    "operationCount": 128,
     "tools": {
         "list_forms": "listForms",
         "get_form": "getForm",
@@ -95,6 +95,7 @@
     "tags": {
         "Forms": "Forms: list, structure, create and edit, plus field display rules, cooperators, copy, move and other related operations.",
         "Form Settings": "Form settings: submission settings, access policy, Webhook, theme, closing rules, exam / evaluation scene settings.",
+        "Plugins": "Plugin center plugins (check-in for now). A plugin campaign is bound to one form, and only its creator can see and change it. The account must have enabled the plugin in the plugin center, or the request returns 402.",
         "Entries": "Form entries: list, query, create, update, delete and batch operations.",
         "Tables": "Tables (kind=table): structure and entries; field types are limited to the column types tables support.",
         "Views": "Form / table views (view filters, sort, column configuration) and reading entries through a view.",