level-up-mcp-server-cn 0.4.0

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AACA,+DAA+D;AAC/D,0DAA0D;AAC1D,+DAA+D;AAC/D,4DAA4D;AAC5D,uCAAuC;AACvC,uCAAuC;AACvC,+CAA+C;AAC/C,+CAA+C;AAC/C,EAAE;AACF,cAAc;AACd,4CAA4C;AAC5C,kBAAkB;AAClB,EAAE;AACF,yEAAyE;AACzE,wDAAwD;AACxD,EAAE;AACF,kDAAkD;AAClD,gFAAgF;AAChF,EAAE;AACF,uBAAuB;AACvB,iEAAiE;AACjE,EAAE;AACF,mCAAmC;AACnC,kEAAkE;AAClE,wEAAwE;AACxE,uDAAuD;AACvD,+DAA+D;AAC/D,EAAE;AACF,4BAA4B;AAC5B,oEAAoE;AACpE,4DAA4D;AAC5D,yDAAyD;AACzD,+DAA+D;AAE/D,OAAO,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AACpE,OAAO,EAAE,oBAAoB,EAAE,MAAM,2CAA2C,CAAC;AACjF,OAAO,EAAE,6BAA6B,EAAE,MAAM,oDAAoD,CAAC;AACnG,OAAO,OAAO,MAAM,SAAS,CAAC;AAE9B,OAAO,EAAE,WAAW,EAAE,cAAc,EAAE,MAAM,gBAAgB,CAAC;AAC7D,OAAO,EAAE,WAAW,EAAE,QAAQ,EAAE,MAAM,wBAAwB,CAAC;AAC/D,iDAAiD;AACjD,OAAO,EAAE,iBAAiB,EAAE,MAAM,kBAAkB,CAAC;AACrD,OAAO,EAAE,kBAAkB,EAAE,MAAM,mBAAmB,CAAC;AACvD,OAAO,EAAE,kBAAkB,EAAE,MAAM,mBAAmB,CAAC;AACvD,OAAO,EAAE,iBAAiB,EAAE,MAAM,kBAAkB,CAAC;AACrD,OAAO,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AAChD,OAAO,EAAE,wBAAwB,EAAE,MAAM,yBAAyB,CAAC;AACnE,OAAO,EAAE,qBAAqB,EAAE,MAAM,qBAAqB,CAAC;AAC5D,OAAO,EAAE,wBAAwB,EAAE,MAAM,yBAAyB,CAAC;AACnE,OAAO,EAAE,mBAAmB,EAAE,MAAM,oBAAoB,CAAC;AACzD,OAAO,EAAE,oBAAoB,EAAE,MAAM,oBAAoB,CAAC;AAC1D,OAAO,EAAE,kBAAkB,EAAE,MAAM,mBAAmB,CAAC;AACvD,OAAO,EAAE,kBAAkB,EAAE,MAAM,kBAAkB,CAAC;AACtD,OAAO,EAAE,mBAAmB,EAAE,MAAM,mBAAmB,CAAC;AACxD,OAAO,EAAE,uBAAuB,EAAE,MAAM,wBAAwB,CAAC;AACjE,OAAO,EAAE,sBAAsB,EAAE,MAAM,sBAAsB,CAAC;AAE9D,oEAAoE;AACpE,OAAO,EAAE,yBAAyB,EAAE,MAAM,gCAAgC,CAAC;AAC3E,OAAO,EAAE,uBAAuB,EAAE,MAAM,8BAA8B,CAAC;AACvE,OAAO,EAAE,wBAAwB,EAAE,MAAM,+BAA+B,CAAC;AACzE,OAAO,EAAE,uBAAuB,EAAE,MAAM,8BAA8B,CAAC;AACvE,OAAO,EAAE,oBAAoB,EAAE,MAAM,2BAA2B,CAAC;AACjE,OAAO,EAAE,sBAAsB,EAAE,MAAM,6BAA6B,CAAC;AACrE,OAAO,EAAE,uBAAuB,EAAE,MAAM,8BAA8B,CAAC;AACvE,OAAO,EAAE,wBAAwB,EAAE,MAAM,+BAA+B,CAAC;AAEzE,qDAAqD;AAErD,WAAW,EAAE,CAAC;AAEd,sCAAsC;AACtC,IAAI,OAAO,CAAC,GAAG,CAAC,eAAe,EAAE,CAAC;IAChC,OAAO,CAAC,KAAK,CAAC,wBAAwB,OAAO,CAAC,GAAG,CAAC,eAAe,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC;AACtF,CAAC;KAAM,CAAC;IACN,OAAO,CAAC,KAAK,CAAC,6CAA6C,CAAC,CAAC;AAC/D,CAAC;AACD,IAAI,OAAO,CAAC,GAAG,CAAC,gBAAgB,EAAE,CAAC;IACjC,OAAO,CAAC,KAAK,CAAC,yBAAyB,OAAO,CAAC,GAAG,CAAC,gBAAgB,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC;AACxF,CAAC;AAED,sDAAsD;AAEtD,2DAA2D;AAC3D,6DAA6D;AAC7D,MAAM,MAAM,GAAG,IAAI,SAAS,CAAC;IAC3B,IAAI,EAAE,WAAW;IACjB,OAAO,EAAE,cAAc;CACxB,CAAC,CAAC;AAEH,mDAAmD;AAEnD,OAAO,CAAC,KAAK,CAAC,oBAAoB,cAAc,EAAE,CAAC,CAAC;AACpD,OAAO,CAAC,KAAK,CAAC,qCAAqC,CAAC,CAAC;AAErD,2FAA2F;AAC3F,yEAAyE;AACzE,MAAM,QAAQ,GAAG,OAAO,CAAC,GAAG,CAAC,iBAAiB,IAAI,SAAS,CAAC;AAE5D,IAAI,QAAQ,KAAK,QAAQ,EAAE,CAAC;IAC1B,OAAO,CAAC,KAAK,CAAC,4BAA4B,CAAC,CAAC;IAE5C,iBAAiB,CAAC,MAAM,CAAC,CAAC;IAC1B,kBAAkB,CAAC,MAAM,CAAC,CAAC;IAC3B,kBAAkB,CAAC,MAAM,CAAC,CAAC;IAC3B,iBAAiB,CAAC,MAAM,CAAC,CAAC;IAC1B,mBAAmB,CAAC,MAAM,CAAC,CAAC;IAC5B,IAAI,OAAO,CAAC,GAAG,CAAC,sBAAsB,KAAK,OAAO,EAAE,CAAC;QACnD,kBAAkB,CAAC,MAAM,CAAC,CAAC;IAC7B,CAAC;IACD,oBAAoB,CAAC,MAAM,CAAC,CAAC;IAC7B,eAAe,CAAC,MAAM,CAAC,CAAC;IACxB,wBAAwB,CAAC,MAAM,CAAC,CAAC;IACjC,qBAAqB,CAAC,MAAM,CAAC,CAAC;IAC9B,wBAAwB,CAAC,MAAM,CAAC,CAAC;IACjC,kBAAkB,CAAC,MAAM,CAAC,CAAC;IAC3B,mBAAmB,CAAC,MAAM,CAAC,CAAC;IAC5B,uBAAuB,CAAC,MAAM,CAAC,CAAC;IAChC,sBAAsB,CAAC,MAAM,CAAC,CAAC;AACjC,CAAC;KAAM,CAAC;IACN,OAAO,CAAC,KAAK,CAAC,0BAA0B,CAAC,CAAC;IAE1C,yBAAyB,CAAC,MAAM,CAAC,CAAC;IAClC,uBAAuB,CAAC,MAAM,CAAC,CAAC;IAChC,wBAAwB,CAAC,MAAM,CAAC,CAAC;IACjC,uBAAuB,CAAC,MAAM,CAAC,CAAC;IAChC,oBAAoB,CAAC,MAAM,CAAC,CAAC;IAC7B,sBAAsB,CAAC,MAAM,CAAC,CAAC;IAC/B,uBAAuB,CAAC,MAAM,CAAC,CAAC;IAChC,IAAI,OAAO,CAAC,GAAG,CAAC,sBAAsB,KAAK,OAAO,EAAE,CAAC;QACnD,wBAAwB,CAAC,MAAM,CAAC,CAAC;IACnC,CAAC;AACH,CAAC;AAED,OAAO,CAAC,KAAK,CAAC,uCAAuC,CAAC,CAAC;AAEvD,8DAA8D;AAE9D,MAAM,CAAC,MAAM,CACX,eAAe,EACf,sCAAsC,EACtC,GAAG,EAAE,CAAC,CAAC;IACL,QAAQ,EAAE;QACR;YACE,IAAI,EAAE,MAAe;YACrB,OAAO,EAAE;gBACP,IAAI,EAAE,MAAe;gBACrB,IAAI,EAAE,0FAA0F;aACjG;SACF;KACF;CACF,CAAC,CACH,CAAC;AACF,OAAO,CAAC,KAAK,CAAC,kCAAkC,CAAC,CAAC;AAElD,6DAA6D;AAE7D,MAAM,uBAAuB,GAAG;IAC9B,4BAA4B;IAC5B,oBAAoB;IACpB,2BAA2B;IAC3B,wBAAwB;CACzB,CAAC;AAEF,CAAC,KAAK,IAAI,EAAE;IACV,IAAI,CAAC;QACH,MAAM,EAAE,IAAI,EAAE,OAAO,EAAE,GAAG,MAAM,QAAQ;aACrC,IAAI,CAAC,WAAW,CAAC,CAAC,MAAM,CAAC,YAAY,CAAC;aACtC,EAAE,CAAC,YAAY,EAAE,uBAAuB,CAAC,CAAC;QAE7C,MAAM,SAAS,GAAG,IAAI,GAAG,CAAC,CAAC,OAAO,IAAI,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,UAAU,CAAC,CAAC,CAAC;QACpE,MAAM,OAAO,GAAG,uBAAuB,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,SAAS,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC;QAEzE,IAAI,OAAO,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;YACvB,OAAO,CAAC,KAAK,CAAC,oCAAoC,CAAC,CAAC;YACpD,KAAK,MAAM,GAAG,IAAI,OAAO,EAAE,CAAC;gBAC1B,OAAO,CAAC,KAAK,CAAC,QAAQ,GAAG,EAAE,CAAC,CAAC;YAC/B,CAAC;YACD,OAAO,CAAC,KAAK,CAAC,oCAAoC,CAAC,CAAC;QACtD,CAAC;IACH,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,CAAC,KAAK,CAAC,kCAAkC,CAAC,CAAC;IACpD,CAAC;AACH,CAAC,CAAC,EAAE,CAAC;AAEL,kDAAkD;AAElD;;;;;GAKG;AACH,KAAK,UAAU,QAAQ;IACrB,OAAO,CAAC,KAAK,CAAC,iBAAiB,CAAC,CAAC;IACjC,OAAO,CAAC,KAAK,CAAC,+BAA+B,CAAC,CAAC;IAE/C,MAAM,SAAS,GAAG,IAAI,oBAAoB,EAAE,CAAC;IAC7C,MAAM,MAAM,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC;AAClC,CAAC;AAED;;;;;;;;;;;GAWG;AACH,KAAK,UAAU,OAAO;IACpB,MAAM,GAAG,GAAG,OAAO,EAAE,CAAC;IACtB,GAAG,CAAC,GAAG,CAAC,OAAO,CAAC,IAAI,EAAE,CAAC,CAAC;IAExB,mBAAmB;IACnB,GAAG,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,GAAG,EAAE,IAAI,EAAE,EAAE;QAC1B,GAAG,CAAC,SAAS,CAAC,wBAAwB,EAAE,SAAS,CAAC,CAAC;QACnD,GAAG,CAAC,SAAS,CAAC,iBAAiB,EAAE,MAAM,CAAC,CAAC;QACzC,GAAG,CAAC,SAAS,CAAC,iBAAiB,EAAE,aAAa,CAAC,CAAC;QAChD,IAAI,EAAE,CAAC;IACT,CAAC,CAAC,CAAC;IAEH,6DAA6D;IAC7D,MAAM,aAAa,GAAG,OAAO,CAAC,GAAG,CAAC,WAAW,IAAI,uBAAuB,CAAC;IACzE,GAAG,CAAC,GAAG,CAAC,CAAC,GAAG,EAAE,GAAG,EAAE,IAAI,EAAE,EAAE;QACzB,MAAM,MAAM,GAAG,GAAG,CAAC,OAAO,CAAC,MAAM,CAAC;QAClC,IAAI,MAAM,KAAK,aAAa,EAAE,CAAC;YAC7B,GAAG,CAAC,SAAS,CAAC,6BAA6B,EAAE,MAAM,CAAC,CAAC;YACrD,GAAG,CAAC,SAAS,CAAC,8BAA8B,EAAE,oBAAoB,CAAC,CAAC;YACpE,GAAG,CAAC,SAAS,CAAC,8BAA8B,EAAE,sBAAsB,CAAC,CAAC;QACxE,CAAC;QACD,IAAI,GAAG,CAAC,MAAM,KAAK,SAAS,EAAE,CAAC;YAAC,GAAG,CAAC,UAAU,CAAC,GAAG,CAAC,CAAC;YAAC,OAAO;QAAC,CAAC;QAC9D,IAAI,EAAE,CAAC;IACT,CAAC,CAAC,CAAC;IAEH,gDAAgD;IAChD,GAAG,CAAC,GAAG,CAAC,SAAS,EAAE,CAAC,IAAI,EAAE,GAAG,EAAE,EAAE;QAC/B,GAAG,CAAC,IAAI,CAAC;YACP,MAAM,EAAE,IAAI;YACZ,MAAM,EAAE,WAAW;YACnB,OAAO,EAAE,cAAc;SACxB,CAAC,CAAC;IACL,CAAC,CAAC,CAAC;IAEH,uDAAuD;IACvD,GAAG,CAAC,IAAI,CAAC,MAAM,EAAE,KAAK,EAAE,GAAG,EAAE,GAAG,EAAE,EAAE;QAClC,wDAAwD;QACxD,MAAM,SAAS,GAAG,IAAI,6BAA6B,CAAC;YAClD,kBAAkB,EAAE,SAAS;YAC7B,kBAAkB,EAAE,IAAI;SACzB,CAAC,CAAC;QAEH,sCAAsC;QACtC,GAAG,CAAC,EAAE,CAAC,OAAO,EAAE,GAAG,EAAE,CAAC,SAAS,CAAC,KAAK,EAAE,CAAC,CAAC;QAEzC,8DAA8D;QAC9D,MAAM,MAAM,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC;QAChC,MAAM,SAAS,CAAC,aAAa,CAAC,GAAG,EAAE,GAAG,EAAE,GAAG,CAAC,IAAI,CAAC,CAAC;IACpD,CAAC,CAAC,CAAC;IAEH,MAAM,IAAI,GAAG,QAAQ,CAAC,OAAO,CAAC,GAAG,CAAC,IAAI,IAAI,MAAM,EAAE,EAAE,CAAC,CAAC;IACtD,IAAI,KAAK,CAAC,IAAI,CAAC,IAAI,IAAI,GAAG,CAAC,IAAI,IAAI,GAAG,KAAK,EAAE,CAAC;QAC5C,OAAO,CAAC,KAAK,CAAC,WAAW,OAAO,CAAC,GAAG,CAAC,IAAI,wBAAwB,CAAC,CAAC;QACnE,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IAClB,CAAC;IACD,GAAG,CAAC,MAAM,CAAC,IAAI,EAAE,GAAG,EAAE;QACpB,OAAO,CAAC,KAAK,CAAC,gBAAgB,CAAC,CAAC;QAChC,OAAO,CAAC,KAAK,CAAC,8BAA8B,IAAI,MAAM,CAAC,CAAC;QACxD,OAAO,CAAC,KAAK,CAAC,4BAA4B,IAAI,WAAW,CAAC,CAAC;IAC7D,CAAC,CAAC,CAAC;AACL,CAAC;AAED,mDAAmD;AAEnD,MAAM,SAAS,GAAG,OAAO,CAAC,GAAG,CAAC,SAAS,IAAI,OAAO,CAAC;AAEnD,IAAI,SAAS,KAAK,MAAM,EAAE,CAAC;IACzB,OAAO,EAAE,CAAC,KAAK,CAAC,CAAC,KAAK,EAAE,EAAE;QACxB,OAAO,CAAC,KAAK,CAAC,eAAe,EAAE,KAAK,CAAC,CAAC;QACtC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IAClB,CAAC,CAAC,CAAC;AACL,CAAC;KAAM,CAAC;IACN,QAAQ,EAAE,CAAC,KAAK,CAAC,CAAC,KAAK,EAAE,EAAE;QACzB,OAAO,CAAC,KAAK,CAAC,gBAAgB,EAAE,KAAK,CAAC,CAAC;QACvC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IAClB,CAAC,CAAC,CAAC;AACL,CAAC"}

package/dist/schemas/common.d.ts

@@ -0,0 +1,33 @@
+import { z } from "zod";
+/** UUID format validation. Supabase uses UUIDs for all primary keys. */
+export declare const uuidSchema: z.ZodString;
+/** Pagination: limit parameter */
+export declare const limitSchema: z.ZodDefault<z.ZodNumber>;
+/** Pagination: offset parameter */
+export declare const offsetSchema: z.ZodDefault<z.ZodNumber>;
+/** Difficulty scale used for tasks (1-7) */
+export declare const difficultySchema: z.ZodNumber;
+/** Completion percentage (0-100) */
+export declare const completionPctSchema: z.ZodNumber;
+export declare const identityProviderSchema: z.ZodEnum<[string, ...string[]]>;
+export declare const performerTypeSchema: z.ZodEnum<[string, ...string[]]>;
+export declare const outputTypeSchema: z.ZodEnum<[string, ...string[]]>;
+export declare const taskStatusSchema: z.ZodEnum<[string, ...string[]]>;
+export declare const userClassSchema: z.ZodEnum<[string, ...string[]]>;
+export declare const agentPlatformSchema: z.ZodEnum<[string, ...string[]]>;
+export declare const xpTierSchema: z.ZodEnum<[string, ...string[]]>;
+export declare const entityTypeSchema: z.ZodEnum<[string, ...string[]]>;
+/** Standard pagination parameters — used by most list_* tools */
+export declare const paginationSchema: z.ZodObject<{
+    limit: z.ZodDefault<z.ZodNumber>;
+    offset: z.ZodDefault<z.ZodNumber>;
+}, "strip", z.ZodTypeAny, {
+    limit: number;
+    offset: number;
+}, {
+    limit?: number | undefined;
+    offset?: number | undefined;
+}>;
+/** Flexible metadata field — allows tools to accept extra JSON data (max 10KB) */
+export declare const metadataSchema: z.ZodEffects<z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>, Record<string, unknown> | undefined, Record<string, unknown> | undefined>;
+//# sourceMappingURL=common.d.ts.map

package/dist/schemas/common.js

@@ -0,0 +1,96 @@
+// ============================================================
+// schemas/common.ts — Reusable Zod validation schemas
+// ============================================================
+// Zod is a "runtime validator" — it checks data WHILE your code
+// runs (not just at compile time like TypeScript alone).
+//
+// Why do we need both TypeScript AND Zod?
+// - TypeScript checks your code when you BUILD it (compile time)
+// - Zod checks INCOMING DATA when tools are actually called
+//
+// Example: an LLM might call levelup_start_task with
+// { difficulty: "banana" }. TypeScript can't catch that because
+// the data comes from outside your code. But Zod will reject it
+// and return a clear error: "Expected number, got string."
+//
+// These are SHARED schemas — patterns that appear in many tools.
+// Each tool file will compose these with tool-specific schemas.
+// ============================================================
+import { z } from "zod";
+import { DEFAULT_PAGE_SIZE, MAX_PAGE_SIZE, IDENTITY_PROVIDERS, PERFORMER_TYPES, OUTPUT_TYPES, TASK_STATUSES, USER_CLASSES, AGENT_PLATFORMS, XP_TIERS, } from "../constants.js";
+// ---------- Primitive validators ----------
+/** UUID format validation. Supabase uses UUIDs for all primary keys. */
+export const uuidSchema = z
+    .string()
+    .uuid("Must be a valid UUID (e.g., '550e8400-e29b-41d4-a716-446655440000')");
+/** Pagination: limit parameter */
+export const limitSchema = z
+    .number()
+    .int("Limit must be a whole number")
+    .min(1, "Minimum limit is 1")
+    .max(MAX_PAGE_SIZE, `Maximum limit is ${MAX_PAGE_SIZE}`)
+    .default(DEFAULT_PAGE_SIZE)
+    .describe(`Maximum results to return (default: ${DEFAULT_PAGE_SIZE}, max: ${MAX_PAGE_SIZE})`);
+/** Pagination: offset parameter */
+export const offsetSchema = z
+    .number()
+    .int("Offset must be a whole number")
+    .min(0, "Offset cannot be negative")
+    .default(0)
+    .describe("Number of results to skip for pagination (default: 0)");
+/** Difficulty scale used for tasks (1-7) */
+export const difficultySchema = z
+    .number()
+    .int()
+    .min(1, "Minimum difficulty is 1")
+    .max(7, "Maximum difficulty is 7")
+    .describe("Task difficulty on a 1-7 scale (default 3, determined by TDI)");
+/** Completion percentage (0-100) */
+export const completionPctSchema = z
+    .number()
+    .int()
+    .min(0)
+    .max(100)
+    .describe("Completion percentage (0-100)");
+// ---------- Enum validators ----------
+// z.enum() creates a validator that only accepts specific string values.
+// The "as [string, ...string[]]" syntax is a TypeScript trick to tell
+// Zod that the array has at least one element (required by z.enum).
+export const identityProviderSchema = z
+    .enum(IDENTITY_PROVIDERS)
+    .describe("Identity provider platform");
+export const performerTypeSchema = z
+    .enum(PERFORMER_TYPES)
+    .describe("Who performed the task");
+export const outputTypeSchema = z
+    .enum(OUTPUT_TYPES)
+    .describe("Type of output produced: conversational (1x), deliverable (1.5-2x), deployed (2-3x)");
+export const taskStatusSchema = z
+    .enum(TASK_STATUSES)
+    .describe("Current task status");
+export const userClassSchema = z
+    .enum(USER_CLASSES)
+    .describe("User class track");
+export const agentPlatformSchema = z
+    .enum(AGENT_PLATFORMS)
+    .describe("Agent's hosting platform");
+export const xpTierSchema = z
+    .enum(XP_TIERS)
+    .describe("XP base tier: micro(1-3), light(3-5), standard(10-25), complex(30-60), major(75-150)");
+export const entityTypeSchema = z
+    .enum(["user", "agent"])
+    .describe("Entity type: 'user' or 'agent'");
+// ---------- Composite schemas ----------
+// These combine multiple fields that appear together in many tools.
+/** Standard pagination parameters — used by most list_* tools */
+export const paginationSchema = z.object({
+    limit: limitSchema,
+    offset: offsetSchema,
+});
+/** Flexible metadata field — allows tools to accept extra JSON data (max 10KB) */
+export const metadataSchema = z
+    .record(z.unknown())
+    .optional()
+    .refine((val) => !val || JSON.stringify(val).length <= 10_000, "Metadata too large (max 10KB when serialized)")
+    .describe("Optional extra data as key-value pairs (JSON object, max 10KB)");
+//# sourceMappingURL=common.js.map

package/dist/schemas/common.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"common.js","sourceRoot":"","sources":["../../src/schemas/common.ts"],"names":[],"mappings":"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"}

package/dist/services/dispatcher.d.ts

@@ -0,0 +1,27 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { toMcpResponse } from "./register.js";
+/**
+ * An action handler function — receives validated params and returns an MCP response.
+ * The `action` field is already stripped; params contain only the action-specific fields.
+ */
+export type ActionHandler = (params: Record<string, unknown>) => Promise<ReturnType<typeof toMcpResponse>>;
+/**
+ * Action definition for a dispatcher.
+ */
+export interface ActionDef {
+    /** Short description shown in the action list */
+    description: string;
+    /** The handler function */
+    handler: ActionHandler;
+}
+/**
+ * Register a category dispatcher tool on the MCP server.
+ *
+ * Instead of registering 10+ individual tools, this registers ONE tool
+ * with an `action` parameter that routes to the correct handler.
+ *
+ * The tool description lists all available actions — this is the only
+ * schema the LLM sees, dramatically reducing token usage.
+ */
+export declare function registerDispatcher(server: McpServer, toolName: string, categoryDescription: string, actions: Record<string, ActionDef>): void;
+//# sourceMappingURL=dispatcher.d.ts.map

package/dist/services/dispatcher.js

@@ -0,0 +1,47 @@
+// ============================================================
+// services/dispatcher.ts — Category dispatcher framework
+// ============================================================
+// Creates a single MCP tool that routes to multiple action handlers.
+// Reduces 75 tools → 8 dispatchers, cutting ~93% of token overhead.
+// ============================================================
+import { z } from "zod";
+import { toMcpResponse } from "./register.js";
+import { fail } from "./errors.js";
+/**
+ * Register a category dispatcher tool on the MCP server.
+ *
+ * Instead of registering 10+ individual tools, this registers ONE tool
+ * with an `action` parameter that routes to the correct handler.
+ *
+ * The tool description lists all available actions — this is the only
+ * schema the LLM sees, dramatically reducing token usage.
+ */
+export function registerDispatcher(server, toolName, categoryDescription, actions) {
+    const actionNames = Object.keys(actions);
+    // Build a compact action list for the description
+    const actionList = actionNames
+        .map((name) => `  - ${name}: ${actions[name].description}`)
+        .join("\n");
+    const fullDescription = `${categoryDescription}\n\n操作列表：\n${actionList}\n\n传入 { "action": "<名称>", ...params }，其中 params 取决于具体操作。`;
+    server.tool(toolName, fullDescription, {
+        action: z.enum(actionNames)
+            .describe("要执行的操作"),
+        params: z.record(z.unknown()).default({})
+            .describe("操作特定参数"),
+    }, async ({ action, params }) => {
+        const actionDef = actions[action];
+        if (!actionDef) {
+            return toMcpResponse(fail(`未知操作 "${action}"`, `可用操作：${actionNames.join(", ")}`));
+        }
+        try {
+            return await actionDef.handler(params);
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            console.error(`[${toolName}:${action}] Error:`, message);
+            return toMcpResponse(fail(`操作 "${action}" 失败：${message}`));
+        }
+    });
+    console.error(`  ✅ ${toolName} (${actionNames.length} actions: ${actionNames.join(", ")})`);
+}
+//# sourceMappingURL=dispatcher.js.map

package/dist/services/dispatcher.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"dispatcher.js","sourceRoot":"","sources":["../../src/services/dispatcher.ts"],"names":[],"mappings":"AAAA,+DAA+D;AAC/D,yDAAyD;AACzD,+DAA+D;AAC/D,qEAAqE;AACrE,oEAAoE;AACpE,+DAA+D;AAG/D,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,EAAE,aAAa,EAAE,MAAM,eAAe,CAAC;AAC9C,OAAO,EAAE,IAAI,EAAE,MAAM,aAAa,CAAC;AAkBnC;;;;;;;;GAQG;AACH,MAAM,UAAU,kBAAkB,CAChC,MAAiB,EACjB,QAAgB,EAChB,mBAA2B,EAC3B,OAAkC;IAElC,MAAM,WAAW,GAAG,MAAM,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;IAEzC,kDAAkD;IAClD,MAAM,UAAU,GAAG,WAAW;SAC3B,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,OAAO,IAAI,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC,WAAW,EAAE,CAAC;SAC1D,IAAI,CAAC,IAAI,CAAC,CAAC;IAEd,MAAM,eAAe,GAAG,GAAG,mBAAmB,cAAc,UAAU,2DAA2D,CAAC;IAElI,MAAM,CAAC,IAAI,CACT,QAAQ,EACR,eAAe,EACf;QACE,MAAM,EAAE,CAAC,CAAC,IAAI,CAAC,WAAoC,CAAC;aACjD,QAAQ,CAAC,QAAQ,CAAC;QACrB,MAAM,EAAE,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,OAAO,EAAE,CAAC,CAAC,OAAO,CAAC,EAAE,CAAC;aACtC,QAAQ,CAAC,QAAQ,CAAC;KACtB,EACD,KAAK,EAAE,EAAE,MAAM,EAAE,MAAM,EAAE,EAAE,EAAE;QAC3B,MAAM,SAAS,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;QAClC,IAAI,CAAC,SAAS,EAAE,CAAC;YACf,OAAO,aAAa,CAAC,IAAI,CACvB,SAAS,MAAM,GAAG,EAClB,QAAQ,WAAW,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CACjC,CAAC,CAAC;QACL,CAAC;QAED,IAAI,CAAC;YACH,OAAO,MAAM,SAAS,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC;QACzC,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,MAAM,OAAO,GAAG,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;YACjE,OAAO,CAAC,KAAK,CAAC,IAAI,QAAQ,IAAI,MAAM,UAAU,EAAE,OAAO,CAAC,CAAC;YACzD,OAAO,aAAa,CAAC,IAAI,CAAC,OAAO,MAAM,QAAQ,OAAO,EAAE,CAAC,CAAC,CAAC;QAC7D,CAAC;IACH,CAAC,CACF,CAAC;IAEF,OAAO,CAAC,KAAK,CAAC,OAAO,QAAQ,KAAK,WAAW,CAAC,MAAM,aAAa,WAAW,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;AAC9F,CAAC"}

package/dist/services/errors.d.ts

@@ -0,0 +1,56 @@
+import type { ToolError, ToolResult, ToolSuccess } from "../types.js";
+/**
+ * Create a success response envelope.
+ *
+ * Every tool wraps its return value in this so the LLM always
+ * gets a predictable shape: { success: true, data: ... }
+ *
+ * @example
+ *   return ok({ user_id: "abc-123", username: "alice" });
+ */
+export declare function ok<T>(data: T): ToolSuccess<T>;
+/**
+ * Create an error response envelope.
+ *
+ * The `suggestion` field tells the LLM what to try next.
+ * This is critical for MCP — without it, the agent might
+ * just retry the same failing call in a loop.
+ *
+ * @example
+ *   return fail(
+ *     "User not found",
+ *     "Check the user_id is a valid UUID, or use levelup_find_user to look them up"
+ *   );
+ */
+export declare function fail(error: string, suggestion?: string): ToolError;
+/**
+ * Convert a Supabase error into a user-friendly ToolError.
+ *
+ * Supabase errors come in a specific format:
+ *   { message: string, details: string, hint: string, code: string }
+ *
+ * We map common Postgres error codes to helpful messages.
+ */
+export declare function handleSupabaseError(error: {
+    message: string;
+    code?: string;
+    details?: string;
+    hint?: string;
+}, context?: string): ToolError;
+/**
+ * Wrap an async tool handler with standard error catching.
+ *
+ * This is a "higher-order function" — a function that takes
+ * a function and returns a new function. It's like wrapping
+ * a gift: the original function is inside, but now it has
+ * automatic error handling wrapped around it.
+ *
+ * @example
+ *   // Instead of writing try/catch in every tool:
+ *   const handler = withErrorHandling("register_user", async (params) => {
+ *     // ... your logic here, just return ok() or fail()
+ *     return ok({ user_id: "abc" });
+ *   });
+ */
+export declare function withErrorHandling<TParams, TData>(toolName: string, handler: (params: TParams) => Promise<ToolResult<TData>>): (params: TParams) => Promise<ToolResult<TData>>;
+//# sourceMappingURL=errors.d.ts.map

package/dist/services/errors.js

@@ -0,0 +1,99 @@
+// ============================================================
+// services/errors.ts — Centralized error handling
+// ============================================================
+// Instead of writing try/catch in every tool with different
+// error messages, we funnel all errors through these helpers.
+// This gives us:
+//   1. Consistent error format across all 69 tools
+//   2. Actionable messages (tells the LLM what to do next)
+//   3. One place to update if we change error handling later
+// ============================================================
+/**
+ * Create a success response envelope.
+ *
+ * Every tool wraps its return value in this so the LLM always
+ * gets a predictable shape: { success: true, data: ... }
+ *
+ * @example
+ *   return ok({ user_id: "abc-123", username: "alice" });
+ */
+export function ok(data) {
+    return { success: true, data };
+}
+/**
+ * Create an error response envelope.
+ *
+ * The `suggestion` field tells the LLM what to try next.
+ * This is critical for MCP — without it, the agent might
+ * just retry the same failing call in a loop.
+ *
+ * @example
+ *   return fail(
+ *     "User not found",
+ *     "Check the user_id is a valid UUID, or use levelup_find_user to look them up"
+ *   );
+ */
+export function fail(error, suggestion) {
+    return { success: false, error, suggestion };
+}
+/**
+ * Convert a Supabase error into a user-friendly ToolError.
+ *
+ * Supabase errors come in a specific format:
+ *   { message: string, details: string, hint: string, code: string }
+ *
+ * We map common Postgres error codes to helpful messages.
+ */
+export function handleSupabaseError(error, context = "operation") {
+    // Postgres error code reference:
+    // 23505 = unique_violation (e.g., duplicate handle)
+    // 23503 = foreign_key_violation (e.g., referencing nonexistent user)
+    // 23502 = not_null_violation (e.g., missing required field)
+    // 42P01 = undefined_table
+    // PGRST116 = PostgREST "not exactly one row" (from .single())
+    const code = error.code || "";
+    if (code === "23505") {
+        return fail(`重复条目：${error.details || error.message}`, "该值已存在，请尝试使用其他值。");
+    }
+    if (code === "23503") {
+        return fail(`引用的记录未找到：${error.details || error.message}`, "请确保您引用的ID在数据库中存在。");
+    }
+    if (code === "23502") {
+        return fail(`缺少必填字段：${error.details || error.message}`, "请检查是否提供了所有必需的参数。");
+    }
+    if (code === "PGRST116") {
+        return fail(`在${context}期间未找到匹配的记录`, "请验证ID是否正确以及记录是否存在。");
+    }
+    // 未知错误的通用处理
+    return fail(`${context}期间发生数据库错误：${error.message}`, error.hint || "请检查参数后重试。");
+}
+/**
+ * Wrap an async tool handler with standard error catching.
+ *
+ * This is a "higher-order function" — a function that takes
+ * a function and returns a new function. It's like wrapping
+ * a gift: the original function is inside, but now it has
+ * automatic error handling wrapped around it.
+ *
+ * @example
+ *   // Instead of writing try/catch in every tool:
+ *   const handler = withErrorHandling("register_user", async (params) => {
+ *     // ... your logic here, just return ok() or fail()
+ *     return ok({ user_id: "abc" });
+ *   });
+ */
+export function withErrorHandling(toolName, handler) {
+    return async (params) => {
+        try {
+            return await handler(params);
+        }
+        catch (error) {
+            // Log the full error for debugging (goes to stderr, not to the LLM)
+            console.error(`[${toolName}] Unexpected error:`, error);
+            // Return a clean error to the LLM
+            const message = error instanceof Error ? error.message : String(error);
+            return fail(`${toolName}中发生意外错误：${message}`, "这可能是服务器问题，请重试或联系支持团队。");
+        }
+    };
+}
+//# sourceMappingURL=errors.js.map

package/dist/services/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../../src/services/errors.ts"],"names":[],"mappings":"AAAA,+DAA+D;AAC/D,kDAAkD;AAClD,+DAA+D;AAC/D,4DAA4D;AAC5D,8DAA8D;AAC9D,iBAAiB;AACjB,mDAAmD;AACnD,2DAA2D;AAC3D,6DAA6D;AAC7D,+DAA+D;AAI/D;;;;;;;;GAQG;AACH,MAAM,UAAU,EAAE,CAAI,IAAO;IAC3B,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC;AACjC,CAAC;AAED;;;;;;;;;;;;GAYG;AACH,MAAM,UAAU,IAAI,CAAC,KAAa,EAAE,UAAmB;IACrD,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,KAAK,EAAE,UAAU,EAAE,CAAC;AAC/C,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,mBAAmB,CACjC,KAA0E,EAC1E,UAAkB,WAAW;IAE7B,iCAAiC;IACjC,oDAAoD;IACpD,qEAAqE;IACrE,4DAA4D;IAC5D,0BAA0B;IAC1B,8DAA8D;IAE9D,MAAM,IAAI,GAAG,KAAK,CAAC,IAAI,IAAI,EAAE,CAAC;IAE9B,IAAI,IAAI,KAAK,OAAO,EAAE,CAAC;QACrB,OAAO,IAAI,CACT,QAAQ,KAAK,CAAC,OAAO,IAAI,KAAK,CAAC,OAAO,EAAE,EACxC,iBAAiB,CAClB,CAAC;IACJ,CAAC;IAED,IAAI,IAAI,KAAK,OAAO,EAAE,CAAC;QACrB,OAAO,IAAI,CACT,YAAY,KAAK,CAAC,OAAO,IAAI,KAAK,CAAC,OAAO,EAAE,EAC5C,mBAAmB,CACpB,CAAC;IACJ,CAAC;IAED,IAAI,IAAI,KAAK,OAAO,EAAE,CAAC;QACrB,OAAO,IAAI,CACT,UAAU,KAAK,CAAC,OAAO,IAAI,KAAK,CAAC,OAAO,EAAE,EAC1C,kBAAkB,CACnB,CAAC;IACJ,CAAC;IAED,IAAI,IAAI,KAAK,UAAU,EAAE,CAAC;QACxB,OAAO,IAAI,CACT,IAAI,OAAO,YAAY,EACvB,oBAAoB,CACrB,CAAC;IACJ,CAAC;IAED,YAAY;IACZ,OAAO,IAAI,CACT,GAAG,OAAO,aAAa,KAAK,CAAC,OAAO,EAAE,EACtC,KAAK,CAAC,IAAI,IAAI,WAAW,CAC1B,CAAC;AACJ,CAAC;AAED;;;;;;;;;;;;;;GAcG;AACH,MAAM,UAAU,iBAAiB,CAC/B,QAAgB,EAChB,OAAwD;IAExD,OAAO,KAAK,EAAE,MAAe,EAA8B,EAAE;QAC3D,IAAI,CAAC;YACH,OAAO,MAAM,OAAO,CAAC,MAAM,CAAC,CAAC;QAC/B,CAAC;QAAC,OAAO,KAAc,EAAE,CAAC;YACxB,oEAAoE;YACpE,OAAO,CAAC,KAAK,CAAC,IAAI,QAAQ,qBAAqB,EAAE,KAAK,CAAC,CAAC;YAExD,kCAAkC;YAClC,MAAM,OAAO,GACX,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;YACzD,OAAO,IAAI,CACT,GAAG,QAAQ,WAAW,OAAO,EAAE,EAC/B,uBAAuB,CACxB,CAAC;QACJ,CAAC;IACH,CAAC,CAAC;AACJ,CAAC"}

package/dist/services/format.d.ts

@@ -0,0 +1,74 @@
+import type { PaginatedResponse, ToolResult } from "../types.js";
+/**
+ * Format a ToolResult as a text string for the MCP response.
+ *
+ * This is the final step before returning from any tool —
+ * it converts our structured result into the text content
+ * that the MCP protocol expects.
+ */
+export declare function formatToolResponse(result: ToolResult): string;
+/**
+ * Build a standard paginated response object.
+ *
+ * Used by any tool that returns lists (list_tasks, list_agents, etc).
+ * Gives the LLM all the info it needs to paginate:
+ *   - total: how many items exist in total
+ *   - has_more: whether there's another page
+ *   - next_offset: what offset to use for the next page
+ *
+ * @param items - The items for this page
+ * @param total - Total count of all matching items
+ * @param offset - Current offset (how many items were skipped)
+ *
+ * @example
+ *   const response = paginate(users, totalCount, params.offset);
+ *   return ok(response);
+ */
+export declare function paginate<T>(items: T[], total: number, offset: number): PaginatedResponse<T>;
+/**
+ * Truncate a response string if it exceeds CHARACTER_LIMIT.
+ *
+ * LLMs have context windows. If a tool returns a 500KB response,
+ * it wastes context and slows everything down. This function
+ * truncates gracefully and tells the LLM to use pagination.
+ */
+export declare function truncateIfNeeded(text: string, hint?: string): string;
+/**
+ * Generate a random profile code in the format LVL-XXXX-XXXX.
+ *
+ * Uses alphanumeric characters (no O/0/I/1 to avoid confusion).
+ * This is used during user registration.
+ */
+export declare function generateProfileCode(): string;
+/**
+ * Generate a random link code in the format LINK-XXXX.
+ */
+export declare function generateLinkCode(): string;
+/**
+ * Format rank display with stars.
+ *
+ * Each rank covers a range of levels. Stars show progress within that range.
+ * E.g. Rank E covers levels 1-5:
+ *   Level 1 → "Rank E ★☆☆☆☆ — Analyst"
+ *   Level 3 → "Rank E ★★★☆☆ — Analyst"
+ *   Level 5 → "Rank E ★★★★★ — Analyst"
+ *
+ * @param level - Current level (1-30)
+ * @param rankLetter - e.g. "E", "D", "C", "B", "A", "S"
+ * @param rankName - e.g. "Analyst", "Novice", "Pathfinder", "Enlightened"
+ * @param minLevel - The rank's min_level from rank_definitions
+ * @param maxLevel - The rank's max_level from rank_definitions
+ */
+export declare function formatRankDisplay(level: number, rankLetter: string | null, rankName: string | null, minLevel: number, maxLevel: number): {
+    rank_display: string;
+    stars: string;
+    stars_earned: number;
+    stars_total: number;
+};
+/**
+ * Format a timestamp string to a human-readable form.
+ * Converts ISO strings like "2025-03-13T10:30:00Z" to
+ * "Mar 13, 2025, 10:30 AM"
+ */
+export declare function formatTimestamp(iso: string): string;
+//# sourceMappingURL=format.d.ts.map

package/dist/services/format.js

@@ -0,0 +1,144 @@
+// ============================================================
+// services/format.ts — Response formatting helpers
+// ============================================================
+// MCP tools return text to the LLM. This file provides helpers
+// to format that text consistently — either as JSON (for when
+// the LLM needs to process data) or Markdown (for when a human
+// will read it).
+//
+// Why both formats?
+// - JSON: compact, easy for agents to parse, good for chaining
+//   tool calls (e.g., get user → start task with user_id)
+// - Markdown: readable, good for when the user asks "show me
+//   my profile" and expects a nice display
+// ============================================================
+import { CHARACTER_LIMIT } from "../constants.js";
+/**
+ * Format a ToolResult as a text string for the MCP response.
+ *
+ * This is the final step before returning from any tool —
+ * it converts our structured result into the text content
+ * that the MCP protocol expects.
+ */
+export function formatToolResponse(result) {
+    return JSON.stringify(result, null, 2);
+}
+/**
+ * Build a standard paginated response object.
+ *
+ * Used by any tool that returns lists (list_tasks, list_agents, etc).
+ * Gives the LLM all the info it needs to paginate:
+ *   - total: how many items exist in total
+ *   - has_more: whether there's another page
+ *   - next_offset: what offset to use for the next page
+ *
+ * @param items - The items for this page
+ * @param total - Total count of all matching items
+ * @param offset - Current offset (how many items were skipped)
+ *
+ * @example
+ *   const response = paginate(users, totalCount, params.offset);
+ *   return ok(response);
+ */
+export function paginate(items, total, offset) {
+    const hasMore = total > offset + items.length;
+    return {
+        total,
+        count: items.length,
+        offset,
+        items,
+        has_more: hasMore,
+        ...(hasMore ? { next_offset: offset + items.length } : {}),
+    };
+}
+/**
+ * Truncate a response string if it exceeds CHARACTER_LIMIT.
+ *
+ * LLMs have context windows. If a tool returns a 500KB response,
+ * it wastes context and slows everything down. This function
+ * truncates gracefully and tells the LLM to use pagination.
+ */
+export function truncateIfNeeded(text, hint = "使用分页（limit + offset）获取更多结果。") {
+    if (text.length <= CHARACTER_LIMIT) {
+        return text;
+    }
+    // Cut roughly in half and add a truncation notice
+    const truncated = text.slice(0, CHARACTER_LIMIT - 200);
+    const notice = `\n\n⚠️ 响应已截断（${text.length} → ${truncated.length} 字符）。${hint}`;
+    return truncated + notice;
+}
+/**
+ * Generate a random profile code in the format LVL-XXXX-XXXX.
+ *
+ * Uses alphanumeric characters (no O/0/I/1 to avoid confusion).
+ * This is used during user registration.
+ */
+export function generateProfileCode() {
+    // Characters that are easy to read (no ambiguous ones)
+    const chars = "2345679ABCDEFGHJKLMNPQRSTUVWXYZ";
+    const segment = () => {
+        let result = "";
+        for (let i = 0; i < 4; i++) {
+            result += chars[Math.floor(Math.random() * chars.length)];
+        }
+        return result;
+    };
+    return `LVL-${segment()}-${segment()}`;
+}
+/**
+ * Generate a random link code in the format LINK-XXXX.
+ */
+export function generateLinkCode() {
+    const chars = "2345679ABCDEFGHJKLMNPQRSTUVWXYZ";
+    let code = "";
+    for (let i = 0; i < 4; i++) {
+        code += chars[Math.floor(Math.random() * chars.length)];
+    }
+    return `LINK-${code}`;
+}
+/**
+ * Format rank display with stars.
+ *
+ * Each rank covers a range of levels. Stars show progress within that range.
+ * E.g. Rank E covers levels 1-5:
+ *   Level 1 → "Rank E ★☆☆☆☆ — Analyst"
+ *   Level 3 → "Rank E ★★★☆☆ — Analyst"
+ *   Level 5 → "Rank E ★★★★★ — Analyst"
+ *
+ * @param level - Current level (1-30)
+ * @param rankLetter - e.g. "E", "D", "C", "B", "A", "S"
+ * @param rankName - e.g. "Analyst", "Novice", "Pathfinder", "Enlightened"
+ * @param minLevel - The rank's min_level from rank_definitions
+ * @param maxLevel - The rank's max_level from rank_definitions
+ */
+export function formatRankDisplay(level, rankLetter, rankName, minLevel, maxLevel) {
+    if (!rankLetter) {
+        return { rank_display: "未定级", stars: "☆☆☆☆☆", stars_earned: 0, stars_total: 5 };
+    }
+    const starsTotal = maxLevel - minLevel + 1;
+    const starsEarned = Math.min(level - minLevel + 1, starsTotal);
+    const stars = "★".repeat(starsEarned) + "☆".repeat(Math.max(0, starsTotal - starsEarned));
+    const name = rankName || "未知";
+    const rankDisplay = `段位 ${rankLetter} ${stars} — ${name}`;
+    return { rank_display: rankDisplay, stars, stars_earned: starsEarned, stars_total: starsTotal };
+}
+/**
+ * Format a timestamp string to a human-readable form.
+ * Converts ISO strings like "2025-03-13T10:30:00Z" to
+ * "Mar 13, 2025, 10:30 AM"
+ */
+export function formatTimestamp(iso) {
+    try {
+        return new Date(iso).toLocaleString("zh-CN", {
+            month: "short",
+            day: "numeric",
+            year: "numeric",
+            hour: "numeric",
+            minute: "2-digit",
+        });
+    }
+    catch {
+        return iso; // Return as-is if parsing fails
+    }
+}
+//# sourceMappingURL=format.js.map

package/dist/services/format.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"format.js","sourceRoot":"","sources":["../../src/services/format.ts"],"names":[],"mappings":"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"}

package/dist/services/ownership.d.ts

@@ -0,0 +1,19 @@
+import { toMcpResponse } from "./register.js";
+/**
+ * Verify that a caller has access to the requested entity's data.
+ *
+ * Rules:
+ *   - If target user_id matches caller_user_id → allowed
+ *   - If target agent_id is owned by caller_user_id → allowed
+ *   - If target is a task, verify caller owns the task's user_id or agent
+ *   - Otherwise → denied
+ *
+ * @returns null if access is allowed, or an MCP error response if denied
+ */
+export declare function verifyOwnership(params: {
+    caller_user_id: string;
+    target_user_id?: string | null;
+    target_agent_id?: string | null;
+    target_task_id?: string | null;
+}): Promise<ReturnType<typeof toMcpResponse> | null>;
+//# sourceMappingURL=ownership.d.ts.map