@jinshuju/mcp 0.3.0 → 0.5.0

package/README.md

@@ -1,7 +1,7 @@
 # @jinshuju/mcp
 
 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.
+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.
 
 Two ways to use it:
 
@@ -49,11 +49,11 @@ 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:
+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                                               |
+| Forms               | list_forms, get_form, create_form, edit_form, copy_form, delete_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                                                                                                                                                     |
@@ -62,11 +62,16 @@ To check it works, ask the assistant to "list my Jinshuju forms".
 | 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                                                                                                                                                                      |
+| Uploads             | prepare_entry_attachment_upload, prepare_form_image_upload, prepare_import_file_upload, 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`.
 
+**Uploads.** A file on disk goes through `prepare_*_upload`, which returns a one-time `upload_url` (valid 30 minutes);
+the client posts the file to it itself (`curl -F file=@<path> <upload_url>`), so its bytes never pass through the model, then uses the returned `attachment_id`.
+That needs a client with a shell that can reach jinshuju.net, such as Claude Code, Cursor or Codex.
+`upload_*` carry the file as Base64 inside the tool call, which only suits small content the model has in hand.
+
 **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")`.

package/dist/analytics.d.ts

@@ -12,7 +12,8 @@
  * - 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;
+ * - distinct_id = the Jinshuju user id (from GET /me, or the token info when the token lacks the users scope; see
+ *   auth.ts); $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.

package/dist/app.js

@@ -35,7 +35,12 @@ export function createApp(options = {}) {
     const cfg = { ...DEFAULTS, ...options.config };
     const fetchImpl = options.fetch ?? ((input, init) => fetch(input, init));
     const api = new JinshujuApi({ baseUrl: cfg.apiBaseUrl, fetch: fetchImpl, timeoutMs: cfg.timeoutMs });
-    const verifier = new TokenVerifier({ api, cacheTtlMs: cfg.tokenCacheTtlMs });
+    const verifier = new TokenVerifier({
+        api,
+        cacheTtlMs: cfg.tokenCacheTtlMs,
+        authServer: cfg.authServer,
+        fetch: fetchImpl
+    });
     const analytics = options.analytics === undefined ? analyticsFromConfig(cfg, fetchImpl) : (options.analytics ?? undefined);
     const instructions = analytics?.collectIntent ? `${INSTRUCTIONS}\n${CONTEXT_INSTRUCTIONS}` : INSTRUCTIONS;
     let metadata;

package/dist/auth.d.ts

@@ -6,6 +6,8 @@
  * - the request's Bearer (an OAuth token or a personal / account access token) goes to API v1 as is;
  * - the API decides whether a token is valid: one light call (GET /me) checks it, and the result is cached by token
  *   hash for a while, so every tool call does not spend an extra API request;
+ * - GET /me also names the user. An OAuth token without the `users` scope gets 403 there, so the user id then comes from
+ *   the authorization server's token info, which answers whatever the token's scopes;
  * - with no token or an invalid one, answers 401 + WWW-Authenticate: Bearer resource_metadata=..., and the client
  *   goes through OAuth from there.
  */
@@ -14,6 +16,10 @@ import type { JinshujuApi } from './api.js';
 export interface VerifierOptions {
     api: JinshujuApi;
     cacheTtlMs: number;
+    /** OAuth authorization server (issuer). When set, a valid token GET /me does not name is looked up at its token info. */
+    authServer?: string;
+    /** The fetch used for the token info lookup; the global fetch by default */
+    fetch?: typeof fetch;
     maxEntries?: number;
     now?: () => number;
 }
@@ -23,12 +29,19 @@ export declare class TokenVerifier {
     private readonly options;
     private readonly cache;
     private readonly now;
+    private readonly fetchImpl;
     constructor(options: VerifierOptions);
     /** Returns AuthInfo when valid, undefined when not. A network failure counts as invalid but is not cached. */
     verify(token: string): Promise<AuthInfo | undefined>;
     forget(token: string): Promise<void>;
+    /**
+     * The user behind an OAuth token, from the authorization server's token info (Doorkeeper's GET /oauth/token/info):
+     * it answers for any scope, and its resource_owner_id is the id GET /me returns. It gives no name. Personal and
+     * account tokens are not OAuth tokens and get 401 there. Best effort: on any failure the user stays unnamed.
+     */
+    private tokenOwner;
 }
-/** The Jinshuju user id in AuthInfo (the id from GET /me), undefined when no user was identified; analytics and Sentry both identify the user by it. */
+/** The Jinshuju user id in AuthInfo (from GET /me or the token info), undefined when no user was identified; analytics and Sentry both identify the user by it. */
 export declare function userIdOf(authInfo: AuthInfo | undefined): string | undefined;
 export declare function bearerToken(request: Request): string | undefined;
 export declare function challenge(resourceMetadataUrl: string, message: string): Response;

package/dist/auth.js

@@ -6,10 +6,14 @@
  * - the request's Bearer (an OAuth token or a personal / account access token) goes to API v1 as is;
  * - the API decides whether a token is valid: one light call (GET /me) checks it, and the result is cached by token
  *   hash for a while, so every tool call does not spend an extra API request;
+ * - GET /me also names the user. An OAuth token without the `users` scope gets 403 there, so the user id then comes from
+ *   the authorization server's token info, which answers whatever the token's scopes;
  * - with no token or an invalid one, answers 401 + WWW-Authenticate: Bearer resource_metadata=..., and the client
  *   goes through OAuth from there.
  */
 import { bearerAuthChallengeResponse, OAuthError, OAuthErrorCode } from '@modelcontextprotocol/server';
+/** Time limit of the token info lookup: it only names the user, so a slow authorization server must not hold up the request for long. */
+const TOKEN_INFO_TIMEOUT_MS = 5_000;
 /** Token hash: the key of the verification cache, and the source of the analytics session id. */
 export async function sha256(text) {
     const digest = await crypto.subtle.digest('SHA-256', new TextEncoder().encode(text));
@@ -19,9 +23,12 @@ export class TokenVerifier {
     options;
     cache = new Map();
     now;
+    fetchImpl;
     constructor(options) {
         this.options = options;
         this.now = options.now ?? Date.now;
+        // Don't store the global fetch as is: called as a method, its `this` is not the global object, and workerd throws Illegal invocation.
+        this.fetchImpl = options.fetch ?? ((input, init) => fetch(input, init));
     }
     /** Returns AuthInfo when valid, undefined when not. A network failure counts as invalid but is not cached. */
     async verify(token) {
@@ -39,7 +46,7 @@ export class TokenVerifier {
             token,
             clientId: 'jinshuju',
             scopes: [],
-            extra: me ? { userId: me.id, userName: me.name } : undefined
+            extra: me ? { userId: me.id, userName: me.name } : await this.tokenOwner(token)
         };
         if (this.cache.size >= (this.options.maxEntries ?? 2000)) {
             const oldest = this.cache.keys().next().value;
@@ -52,8 +59,31 @@ export class TokenVerifier {
     async forget(token) {
         this.cache.delete(await sha256(token));
     }
+    /**
+     * The user behind an OAuth token, from the authorization server's token info (Doorkeeper's GET /oauth/token/info):
+     * it answers for any scope, and its resource_owner_id is the id GET /me returns. It gives no name. Personal and
+     * account tokens are not OAuth tokens and get 401 there. Best effort: on any failure the user stays unnamed.
+     */
+    async tokenOwner(token) {
+        if (!this.options.authServer)
+            return undefined;
+        try {
+            const res = await this.fetchImpl(`${this.options.authServer.replace(/\/$/, '')}/oauth/token/info`, {
+                headers: { Authorization: `Bearer ${token}`, Accept: 'application/json' },
+                signal: AbortSignal.timeout(TOKEN_INFO_TIMEOUT_MS)
+            });
+            if (res.status !== 200)
+                return undefined;
+            const owner = (await res.json()).resource_owner_id;
+            return owner === undefined || owner === null || owner === '' ? undefined : { userId: owner };
+        }
+        catch (error) {
+            console.warn('token info lookup failed:', error);
+            return undefined;
+        }
+    }
 }
-/** The Jinshuju user id in AuthInfo (the id from GET /me), undefined when no user was identified; analytics and Sentry both identify the user by it. */
+/** The Jinshuju user id in AuthInfo (from GET /me or the token info), undefined when no user was identified; analytics and Sentry both identify the user by it. */
 export function userIdOf(authInfo) {
     const id = authInfo?.extra?.userId;
     return id === undefined || id === null || id === '' ? undefined : String(id);

package/dist/generated/meta.json

@@ -2,17 +2,18 @@
     "generatedFrom": {
         "title": "Jinshuju API v1",
         "version": "1.0",
-        "sha256": "288548a94e3932e7"
+        "sha256": "aecc3bef9088dcc7"
     },
     "baseUrl": "https://jinshuju.net/api/v1",
-    "toolCount": 60,
-    "operationCount": 128,
+    "toolCount": 64,
+    "operationCount": 176,
     "tools": {
         "list_forms": "listForms",
         "get_form": "getForm",
         "create_form": "createForm",
         "edit_form": "updateForm",
         "copy_form": "copyForm",
+        "delete_form": "deleteForm",
         "move_form": "moveFormToFolder",
         "list_form_cooperators": "listFormCooperators",
         "get_field_rules": "listFieldRules",
@@ -59,6 +60,9 @@
         "get_current_user": "getCurrentUser",
         "get_current_billing_account": "getBillingAccount",
         "list_account_users": "listBillingAccountUsers",
+        "prepare_entry_attachment_upload": "prepareEntryAttachmentUpload",
+        "prepare_form_image_upload": "prepareFormImageUpload",
+        "prepare_import_file_upload": "prepareImportFileUpload",
         "upload_entry_attachment": "uploadEntryAttachment",
         "upload_form_image": "uploadFormImage",
         "upload_import_file": "uploadImportFile",
@@ -70,24 +74,26 @@
         "count_entries": "countEntries+countEntriesAcrossForms"
     },
     "pointerSchemas": [
-        "BillingAccount",
-        "EntryData",
-        "EvaluationSetting",
-        "EvaluationSettingInput",
-        "FieldDefinition",
         "FieldInput",
         "FieldUpdateInput",
-        "FormSetting",
-        "FormSettingInput",
+        "FieldDefinition",
         "FormSettingWriteInput",
+        "FormSettingInput",
+        "FormSetting",
+        "ThemeInput",
         "FormTheme",
-        "FormView",
+        "EvaluationSettingInput",
+        "EvaluationSetting",
         "FormViewInput",
-        "GoodsItemInput",
-        "OpensearchQuery",
+        "FormView",
         "OpensearchQueryInput",
-        "ThemeInput",
-        "TradeMerchant"
+        "OpensearchQuery",
+        "GoodsItemInput",
+        "EntryData",
+        "TradeMerchant",
+        "BillingAccount",
+        "ExamFieldInput",
+        "EvaluationFieldInput"
     ],
     "omitSchemas": [
         "FormCreateConstraints"
@@ -96,7 +102,7 @@
         "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.",
+        "Entries": "Form entries: list, query, create, update, delete and batch operations, and sending SMS / email to entries.",
         "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.",
         "Comments": "Entry comments.",
@@ -106,9 +112,10 @@
         "Predefined Choices Sets": "Predefined choice sets.",
         "Templates": "Using templates.",
         "Contacts": "Contacts.",
-        "Account": "Current user and account: members, e-invoices, payment history, SMS signature review status.",
+        "Account": "Current user and account: members, e-invoices, payment history, SMS signatures and templates, SMTP accounts.",
         "Trade": "小金商户: merchant and onboarding progress, payment orders, transaction statistics, refunds and payouts.",
-        "Uploads": "Uploading attachments, form images and import files.",
-        "Utilities": "Utility endpoints."
+        "Uploads": "Uploading attachments, form images, license images and import files.",
+        "Utilities": "Utility endpoints.",
+        "Routines": "Routines (`自动任务`): instructions Jiri carries out as you, on a schedule or when data changes, and their runs. The rules and messages are those of the routines page; times are in Beijing time (+08:00). OAuth tokens need the `routines` scope. As routines run unattended and spend AI points, self-registered clients cannot get it; only a registered application with `routines` among its scopes (such as the Jinshuju CLI) can ask for it."
     }
 }