@jinshuju/mcp 0.0.0-stage → 0.3.0

package/LICENSE

@@ -0,0 +1,17 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   Copyright 2026 Jinshuju (金数据)
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -1,3 +1,88 @@
-# Temporary Holding Version
+# @jinshuju/mcp
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+The MCP server for Jinshuju ([jinshuju.net](https://jinshuju.net)): lets Claude, Cursor, Claude Code and other MCP-capable AI tools read and write forms, tables and entries.
+The tools are generated from the [open API v1 openapi.yaml](https://jinshuju.net/api/v1/openapi.yaml) and stay in step with the API; the tool set matches the tools documented for the [Jinshuju MCP Server](https://open.jinshuju.net/mcp) one to one.
+
+Two ways to use it:
+
+- **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://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://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)
+
+Pass an access token (created as above) in `JINSHUJU_ACCESS_TOKEN`:
+
+```bash
+# Claude Code
+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). Each tool maps to one operation in openapi.yaml; a few combine two operations:
+
+| Category            | Tools                                                                                                                                                                                                                               |
+| ------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Forms               | list_forms, get_form, create_form, edit_form, copy_form, move_form, list_form_cooperators, get_field_rules, edit_field_rules, check_field_data, preview_field_type_change, edit_theme                                               |
+| Exams / evaluations | create_exam_form, edit_exam_form, create_evaluation_form, edit_evaluation_form (create / edit the form + its scene settings, two requests)                                                                                          |
+| Entries             | list_entries, get_entry, create_entry, update_entry, delete_entry, create_entries, patch_entries, count_entries, aggregate_entries, get_form_data_summary, search_entries_in_forms, list_form_entry_stats, import_entries_from_file |
+| What I submitted    | list_my_submitted_forms, list_my_submitted_entries, search_my_submitted_entries                                                                                                                                                     |
+| Comments            | list_entry_comments, create_entry_comment, update_entry_comment, delete_entry_comment                                                                                                                                               |
+| Views               | list_form_views, get_form_view, create_form_view, edit_form_view, delete_form_view, list_form_view_entries                                                                                                                          |
+| Tables              | list_tables, get_table, create_table, edit_table, move_table                                                                                                                                                                        |
+| Public queries      | list_opensearch_queries, get_opensearch_query, create_opensearch_query, edit_opensearch_query, get_opensearch_field_suggestions                                                                                                     |
+| Folders / account   | list_folders, create_folder, get_current_user, get_current_billing_account, list_account_users                                                                                                                                      |
+| Uploads             | upload_entry_attachment, upload_form_image, upload_import_file                                                                                                                                                                      |
+| Schemas             | get_schema (reads an openapi schema by name, e.g. FieldInput, TextFieldInput)                                                                                                                                                       |
+
+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 (stdio)
+
+| 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
+
+Building, running and deploying the server: [DEVELOPMENT.md](DEVELOPMENT.md). How it fits together: [ARCHITECTURE.md](ARCHITECTURE.md).
+
+## License
+
+Apache-2.0

package/dist/analytics.d.ts

@@ -0,0 +1,84 @@
+/**
+ * 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:
+ * - 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
+ *   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);
+ * - distinct_id = the Jinshuju user id (from GET /me); $session_id is derived from the token hash: one session per token;
+ * - a session's initialize is reported at most once a day (deduplicated in process; best effort across Workers instances).
+ *
+ * Every other SDK injection stays off: no llm_model / conversation_id arguments, no get_more_tools / send_feedback tools.
+ *
+ * The PostHog client is created per request and shut down when the request ends, never shared across requests:
+ * posthog-node chains each flush onto the previous one, and in Workers a flush still pending when its request's context
+ * ends never settles. A shared client would hang every later request's reporting on that chain (the runtime reports
+ * "code had hung" and not a single event goes out).
+ */
+import type { AuthInfo, McpServer } from '@modelcontextprotocol/server';
+import type { Config } from './config.js';
+/** 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;
+    /** PostHog ingest host */
+    host: string;
+    /** Whether to offer the context argument and report $mcp_intent; on by default */
+    collectIntent?: boolean;
+    /** For tests: the fetch used for reporting */
+    fetch?: typeof fetch;
+    now?: () => number;
+    /** Timeout of one request to PostHog (ms), 5 seconds by default; for tests */
+    requestTimeoutMs?: number;
+}
+/** The analytics handle of one request. */
+export interface RequestAnalytics {
+    /** Sends the events this request buffered and closes the client. On Workers it goes into waitUntil; on Node there is no need to wait. */
+    flush(): Promise<void>;
+}
+export declare class McpAnalytics {
+    readonly collectIntent: boolean;
+    private readonly options;
+    private readonly handshakes;
+    private readonly inflight;
+    private readonly now;
+    constructor(options: AnalyticsOptions);
+    /** Instruments this request's McpServer: the user, the session and the PostHog client are all closed over in this one request. */
+    instrument(server: McpServer, authInfo?: AuthInfo): Promise<RequestAnalytics>;
+    private track;
+    private beforeSend;
+    /** Clients handshake again and again on one connection, and every later handshake reports what the first one already did. */
+    private repeatedHandshake;
+    /** Waits until every request's reporting still in flight has been sent: used before the Node process exits, and in tests. */
+    flush(): Promise<void>;
+    /** Called before the process exits: same as flush. */
+    shutdown(): Promise<void>;
+}
+/** Reports only when POSTHOG_API_KEY is set. */
+export declare function analyticsFromConfig(cfg: Config, fetchImpl?: typeof fetch): McpAnalytics | undefined;

package/dist/analytics.js

@@ -0,0 +1,192 @@
+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';
+/** 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 ' +
+    'are being asked to serve. Leave personal details (phone numbers, ID numbers, addresses) out of it.';
+const KEPT_EVENTS = new Set(['$mcp_initialize', '$mcp_tool_call']);
+/** By default the SDK attaches the (scrubbed) arguments and result; only argument names are recorded, so these go entirely. */
+const DROPPED_PROPERTIES = ['$mcp_parameters', '$mcp_response', '$mcp_tool_description'];
+const HANDSHAKE_TTL_MS = 24 * 60 * 60_000;
+const HANDSHAKE_MAX_ENTRIES = 2000;
+/** Time limit for sending the buffered events when a request ends: covers one request plus one retry */
+const SHUTDOWN_TIMEOUT_MS = 15_000;
+/**
+ * $mcp_input_keys records only argument names declared in openapi: the SDK cannot read the declarations fromJsonSchema
+ * produces, so it gets the full set here (every tool's argument names together, plus get_schema's name). Key names the
+ * model makes up are all recorded as [redacted].
+ */
+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))
+        console.warn(`[posthog-mcp] ${message}`);
+}
+export class McpAnalytics {
+    collectIntent;
+    options;
+    handshakes = new Map();
+    inflight = new Set();
+    now;
+    constructor(options) {
+        this.options = options;
+        this.collectIntent = options.collectIntent ?? true;
+        this.now = options.now ?? Date.now;
+    }
+    /** Instruments this request's McpServer: the user, the session and the PostHog client are all closed over in this one request. */
+    async instrument(server, authInfo) {
+        const sessionId = authInfo ? deriveSessionIdFromMCPSession(await sha256(authInfo.token)) : undefined;
+        const distinctId = userIdOf(authInfo);
+        const posthogOptions = {
+            host: this.options.host,
+            // Events are sent from the server, so the IP is this service's; GeoIP on it would set the user's location to the data center.
+            disableGeoip: true,
+            // One batch per request; a failed send is retried at most once, so it does not outlast the waitUntil limit.
+            requestTimeout: this.options.requestTimeoutMs ?? 5_000,
+            fetchRetryCount: 1,
+            fetchRetryDelay: 1_000,
+            fetch: this.options.fetch
+        };
+        const posthog = new PostHog(this.options.apiKey, posthogOptions);
+        // posthog-node logs a failed send only in debug mode; record it and throw it to the caller on flush (console + Sentry).
+        const failures = [];
+        posthog.on('error', (error) => failures.push(error));
+        instrument(server, posthog, {
+            context: this.collectIntent ? { description: CONTEXT_DESCRIPTION } : false,
+            captureModel: false,
+            enableConversationId: false,
+            enableExceptionAutocapture: false,
+            identify: distinctId ? { distinctId } : null,
+            shouldRecordInputKey: (key, { declared }) => declared || DECLARED_PARAMETER_NAMES.has(key),
+            beforeSend: this.beforeSend(sessionId),
+            logger: warn
+        });
+        return {
+            flush: () => this.track(posthog.shutdown(SHUTDOWN_TIMEOUT_MS).then(() => {
+                if (failures.length)
+                    throw failures[0];
+            }))
+        };
+    }
+    track(flush) {
+        const tracked = flush.finally(() => this.inflight.delete(tracked));
+        this.inflight.add(tracked);
+        return tracked;
+    }
+    beforeSend(sessionId) {
+        return (event) => {
+            if (!KEPT_EVENTS.has(event.event))
+                return null;
+            const props = event.properties;
+            for (const key of DROPPED_PROPERTIES)
+                delete props[key];
+            if (sessionId) {
+                // The SDK opens a new session per request; replace it with the token-derived one. When no user was identified, distinct_id is the session id, so replace that too.
+                if (event.distinct_id === props.$session_id)
+                    event.distinct_id = sessionId;
+                props.$session_id = sessionId;
+            }
+            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;
+        };
+    }
+    /** Clients handshake again and again on one connection, and every later handshake reports what the first one already did. */
+    repeatedHandshake(sessionId) {
+        if (!sessionId)
+            return false;
+        const now = this.now();
+        const until = this.handshakes.get(sessionId);
+        if (until !== undefined && until > now)
+            return true;
+        this.handshakes.delete(sessionId);
+        if (this.handshakes.size >= HANDSHAKE_MAX_ENTRIES) {
+            const oldest = this.handshakes.keys().next().value;
+            if (oldest !== undefined)
+                this.handshakes.delete(oldest);
+        }
+        this.handshakes.set(sessionId, now + HANDSHAKE_TTL_MS);
+        return false;
+    }
+    /** Waits until every request's reporting still in flight has been sent: used before the Node process exits, and in tests. */
+    async flush() {
+        await Promise.allSettled(this.inflight);
+    }
+    /** Called before the process exits: same as flush. */
+    shutdown() {
+        return this.flush();
+    }
+}
+/** Reports only when POSTHOG_API_KEY is set. */
+export function analyticsFromConfig(cfg, fetchImpl) {
+    if (!cfg.posthogApiKey)
+        return undefined;
+    return new McpAnalytics({
+        apiKey: cfg.posthogApiKey,
+        host: cfg.posthogHost,
+        collectIntent: cfg.collectIntent,
+        fetch: fetchImpl
+    });
+}
+//# sourceMappingURL=analytics.js.map

package/dist/api.d.ts

@@ -0,0 +1,54 @@
+/**
+ * Sends one API v1 request for an OperationSpec. It only decides how to send it: URL, query, body, multipart,
+ * credential, timeout and response parsing. What to send comes from the generated operation table; how to report
+ * the result is up to tools.ts.
+ */
+import type { Credential } from './credential.js';
+import type { OperationSpec } from './types.js';
+export interface ApiOptions {
+    baseUrl: string;
+    fetch?: typeof fetch;
+    timeoutMs?: number;
+    userAgent?: string;
+}
+export interface ApiResponse {
+    status: number;
+    /** The parsed JSON; undefined for a non-JSON or empty response */
+    json?: unknown;
+    /** The raw text of a non-JSON response (truncated) */
+    text?: string;
+    /** Argument problems the server reports in report mode (X-API-Input-Warnings) */
+    warnings?: string;
+    retryAfter?: string;
+    rateLimit?: {
+        limit?: string;
+        remaining?: string;
+        reset?: string;
+    };
+}
+export declare class TransportError extends Error {
+    constructor(message: string, options?: {
+        cause?: unknown;
+    });
+}
+type Args = Record<string, unknown>;
+export declare function buildUrl(baseUrl: string, op: OperationSpec, args: Args): URL;
+/** The request body: when flattened, every argument key except the path / query parameters; otherwise the value under body.param. */
+export declare function bodyPayload(op: OperationSpec, args: Args): unknown;
+export declare function buildBody(op: OperationSpec, args: Args): {
+    body?: BodyInit;
+    contentType?: string;
+};
+export declare class JinshujuApi {
+    private readonly options;
+    private readonly fetchImpl;
+    constructor(options: ApiOptions);
+    get baseUrl(): string;
+    /** Sends the request; on 401, has the credential renew once and retries. */
+    call(op: OperationSpec, args: Args, credential: Credential): Promise<ApiResponse>;
+    /** A raw request outside the operation table, for internal calls such as token verification. */
+    raw(method: string, path: string, token: string): Promise<ApiResponse>;
+    private send;
+    private perform;
+}
+export {};

package/dist/api.js

@@ -0,0 +1,167 @@
+export class TransportError extends Error {
+    constructor(message, options) {
+        super(message, options);
+        this.name = 'TransportError';
+    }
+}
+export function buildUrl(baseUrl, op, args) {
+    let path = op.path;
+    for (const p of op.params) {
+        if (p.in !== 'path')
+            continue;
+        const value = args[p.name];
+        if (value === undefined || value === null || value === '')
+            throw new Error(`Missing path parameter ${p.name}`);
+        path = path.replace(`{${p.name}}`, encodeURIComponent(String(value).trim()));
+    }
+    const url = new URL(baseUrl.replace(/\/$/, '') + path);
+    for (const p of op.params) {
+        if (p.in !== 'query')
+            continue;
+        const value = args[p.name];
+        if (value === undefined || value === null || value === '')
+            continue;
+        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));
+        }
+    }
+    return url;
+}
+function scalar(value) {
+    return typeof value === 'string' ? value : JSON.stringify(value);
+}
+function decodeBase64(data) {
+    const raw = data.startsWith('data:') && data.includes(',') ? data.slice(data.indexOf(',') + 1) : data;
+    const bin = atob(raw.replace(/\s+/g, ''));
+    const bytes = new Uint8Array(bin.length);
+    for (let i = 0; i < bin.length; i++)
+        bytes[i] = bin.charCodeAt(i);
+    return bytes;
+}
+/** The request body: when flattened, every argument key except the path / query parameters; otherwise the value under body.param. */
+export function bodyPayload(op, args) {
+    if (!op.body)
+        return undefined;
+    let payload;
+    if (op.body.flatten) {
+        const rest = {};
+        for (const [key, value] of Object.entries(args)) {
+            if (!op.paramNames.includes(key) && value !== undefined)
+                rest[key] = value;
+        }
+        payload = rest;
+    }
+    else {
+        payload = args[op.body.param ?? 'body'];
+    }
+    if (payload === undefined)
+        return undefined;
+    return op.body.wrap ? { [op.body.wrap]: payload } : payload;
+}
+export function buildBody(op, args) {
+    const payload = bodyPayload(op, args);
+    if (!op.body || payload === undefined)
+        return {};
+    if (op.body.contentType === 'application/json') {
+        return { body: JSON.stringify(payload), contentType: 'application/json' };
+    }
+    const fields = payload;
+    const form = new FormData();
+    for (const [key, value] of Object.entries(fields)) {
+        if (key === 'file_base64' || key === 'file_name' || key === 'content_type')
+            continue;
+        if (value === undefined || value === null)
+            continue;
+        form.set(key, scalar(value));
+    }
+    if (typeof fields.file_base64 === 'string') {
+        const bytes = decodeBase64(fields.file_base64);
+        const type = typeof fields.content_type === 'string' ? fields.content_type : 'application/octet-stream';
+        const name = typeof fields.file_name === 'string' ? fields.file_name : 'file';
+        form.set('file', new Blob([bytes], { type }), name);
+    }
+    // fetch sets the multipart Content-Type (with its boundary) itself
+    return { body: form };
+}
+export class JinshujuApi {
+    options;
+    fetchImpl;
+    constructor(options) {
+        this.options = options;
+        // Don't store the global fetch as is: called as a method, its `this` is not the global object, and workerd / browsers throw Illegal invocation.
+        this.fetchImpl = options.fetch ?? ((input, init) => fetch(input, init));
+    }
+    get baseUrl() {
+        return this.options.baseUrl;
+    }
+    /** Sends the request; on 401, has the credential renew once and retries. */
+    async call(op, args, credential) {
+        const first = await this.send(op, args, await credential.token());
+        if (first.status !== 401)
+            return first;
+        if (!(await credential.invalidate()))
+            return first;
+        return this.send(op, args, await credential.token());
+    }
+    /** A raw request outside the operation table, for internal calls such as token verification. */
+    async raw(method, path, token) {
+        return this.perform(method, new URL(this.options.baseUrl.replace(/\/$/, '') + path), token, {});
+    }
+    async send(op, args, token) {
+        const url = buildUrl(this.options.baseUrl, op, args);
+        return this.perform(op.method.toUpperCase(), url, token, buildBody(op, args));
+    }
+    async perform(method, url, token, { body, contentType }) {
+        const headers = {
+            Authorization: `Bearer ${token}`,
+            Accept: 'application/json',
+            'User-Agent': this.options.userAgent ?? 'jinshuju-mcp'
+        };
+        if (contentType)
+            headers['Content-Type'] = contentType;
+        const controller = new AbortController();
+        const timer = setTimeout(() => controller.abort(), this.options.timeoutMs ?? 60_000);
+        let res;
+        try {
+            res = await this.fetchImpl(url, { method, headers, body, signal: controller.signal });
+        }
+        catch (error) {
+            const reason = controller.signal.aborted ? 'Request timed out' : 'Could not reach the Jinshuju API';
+            const detail = error instanceof Error ? `: ${error.message}` : '';
+            throw new TransportError(`${reason} (${method} ${url.pathname})${detail}`, { cause: error });
+        }
+        finally {
+            clearTimeout(timer);
+        }
+        const text = await res.text();
+        const out = { status: res.status };
+        const warnings = res.headers.get('x-api-input-warnings');
+        if (warnings)
+            out.warnings = warnings;
+        const retryAfter = res.headers.get('retry-after');
+        if (retryAfter)
+            out.retryAfter = retryAfter;
+        const rateLimit = {
+            limit: res.headers.get('x-ratelimit-limit') ?? undefined,
+            remaining: res.headers.get('x-ratelimit-remaining') ?? undefined,
+            reset: res.headers.get('x-ratelimit-reset') ?? undefined
+        };
+        if (rateLimit.limit || rateLimit.remaining || rateLimit.reset)
+            out.rateLimit = rateLimit;
+        if (!text)
+            return out;
+        try {
+            out.json = JSON.parse(text);
+        }
+        catch {
+            out.text = text.length > 2000 ? `${text.slice(0, 2000)}…` : text;
+        }
+        return out;
+    }
+}
+//# sourceMappingURL=api.js.map

package/dist/app.d.ts

@@ -0,0 +1,35 @@
+/**
+ * HTTP entry (Hono): the same app runs on Node (node.ts) and Cloudflare Workers (worker.ts).
+ *
+ *   GET  /                                    landing page
+ *   GET  /healthz                             health check
+ *   GET  /.well-known/oauth-protected-resource[/mcp]   RFC 9728, pointing at account.jinshuju.net
+ *   GET  /.well-known/oauth-authorization-server       RFC 8414 mirror (for older clients that probe only the resource domain)
+ *   POST /mcp                                 MCP Streamable HTTP (2026-07-28 stateless; the 2025 handshake falls back to stateless)
+ *
+ * The service may sit under a path prefix (e.g. https://host/jinshuju-mcp/…, with the platform stripping the prefix when
+ * forwarding): JINSHUJU_MCP_PUBLIC_URL gives the public address (prefix included; a comma-separated list gives several,
+ * picked by the request's Host, so a custom domain and the platform's default address both work), and resource_metadata in
+ * the 401 challenge points at the well-known document under this service's own path rather than the domain root; RFC 9728
+ * lets clients fetch the URL the challenge gives. When it is not set, the address is inferred from the request (trusting
+ * the reverse proxy's X-Forwarded-*).
+ *
+ * With POSTHOG_API_KEY set, every request's McpServer gets PostHog MCP analytics (analytics.ts), reported in waitUntil after
+ * the response goes out. Unexpected exceptions go to Sentry (worker.ts initializes it with withSentry; without SENTRY_DSN the
+ * SDK sends nothing; the Node entry is not wired): those a tool handler throws, an unreachable API during token verification,
+ * and anything a route does not catch. A 4xx / 5xx from the API is a normal tool result and is not reported.
+ */
+import { Hono } from 'hono';
+import { type OAuthMetadata } from '@modelcontextprotocol/server';
+import { type McpAnalytics } from './analytics.js';
+import type { Config } from './config.js';
+export interface AppOptions {
+    config?: Partial<Config>;
+    fetch?: typeof fetch;
+    /** For tests: skips fetching the real authorization server metadata */
+    authServerMetadata?: OAuthMetadata;
+    /** Analytics. Omitted, config decides (on only with posthogApiKey); null forces it off; node.ts / tests pass their own instance */
+    analytics?: McpAnalytics | null;
+}
+export declare const MCP_PATH = "/mcp";
+export declare function createApp(options?: AppOptions): Hono;