@jinshuju/mcp 0.0.0-stage → 0.2.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,154 @@
-# 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, 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 use
+
+Server URL: `https://mcp.jinshuju.net/mcp` (until launch, the URL published at open.jinshuju.net/mcp is authoritative).
+
+| 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`                                                 |
+
+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
+
+# Claude Code
+claude mcp add jinshuju -s user -- 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
+```
+
+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:
+
+| 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)                                                                                                                                                       |
+
+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:
+
+- 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.
+
+## 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
+
+## License
+
+Apache-2.0

package/dist/analytics.d.ts

@@ -0,0 +1,64 @@
+/**
+ * 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):
+ * - 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;
+ * - 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';
+/** Asks the model the same question as goldendata's built-in MCP, so $mcp_intent is comparable across the two. */
+export declare const CONTEXT_DESCRIPTION = "Why are you calling this tool? Briefly describe the user's goal.";
+export declare const CONTEXT_INSTRUCTIONS: string;
+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,139 @@
+import { deriveSessionIdFromMCPSession, instrument } from '@posthog/mcp';
+import { PostHog } from 'posthog-node';
+import { sha256, userIdOf } from './auth.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. */
+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 ?? {}))
+]);
+/** 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,
+            eventProperties: () => ({ mcp_caller_type: 'external' }),
+            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;
+            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,166 @@
+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)) {
+            for (const item of value)
+                url.searchParams.append(`${p.name}[]`, scalar(item));
+        }
+        else {
+            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;