@nocoo/base-mcp 0.1.0-alpha.1

package/dist/auth/token.js

@@ -0,0 +1,108 @@
+// ---------------------------------------------------------------------------
+// OAuth Token Management Utilities
+// ---------------------------------------------------------------------------
+/**
+ * Generate a secure random token.
+ *
+ * @param length - Number of random bytes (default 32, produces 64 hex chars)
+ * @returns Hex-encoded random token
+ */
+export function generateToken(length = 32) {
+    const bytes = new Uint8Array(length);
+    crypto.getRandomValues(bytes);
+    return Array.from(bytes)
+        .map((b) => b.toString(16).padStart(2, "0"))
+        .join("");
+}
+/**
+ * Hash a token using SHA-256.
+ *
+ * Tokens should be stored as hashes, never in plaintext.
+ *
+ * @param token - The plaintext token
+ * @returns SHA-256 hash as hex string
+ */
+export async function hashToken(token) {
+    const encoded = new TextEncoder().encode(token);
+    const buffer = await crypto.subtle.digest("SHA-256", encoded);
+    return Array.from(new Uint8Array(buffer))
+        .map((b) => b.toString(16).padStart(2, "0"))
+        .join("");
+}
+/**
+ * Generate a token preview (first 8 characters).
+ *
+ * Used for logging and display without exposing the full token.
+ *
+ * @param token - The plaintext token
+ * @returns First 8 characters
+ */
+export function tokenPreview(token) {
+    return token.slice(0, 8);
+}
+/**
+ * Extract bearer token from Authorization header.
+ *
+ * @param authHeader - The Authorization header value
+ * @returns The token, or null if invalid
+ */
+export function extractBearerToken(authHeader) {
+    if (!authHeader)
+        return null;
+    const match = authHeader.match(/^Bearer\s+(.+)$/i);
+    return match ? match[1] : null;
+}
+/**
+ * Validate an MCP bearer token.
+ *
+ * @param store - Token storage implementation
+ * @param authHeader - The Authorization header value
+ * @returns Validation result
+ */
+export async function validateMcpToken(store, authHeader) {
+    const token = extractBearerToken(authHeader);
+    if (!token) {
+        return {
+            valid: false,
+            error: "Missing or invalid Authorization header",
+            status: 401,
+        };
+    }
+    const hash = await hashToken(token);
+    const record = await store.findByHash(hash);
+    if (!record) {
+        return {
+            valid: false,
+            error: "Invalid token",
+            status: 401,
+        };
+    }
+    if (record.revoked) {
+        return {
+            valid: false,
+            error: "Token has been revoked",
+            status: 401,
+        };
+    }
+    if (record.expires_at && new Date(record.expires_at) < new Date()) {
+        return {
+            valid: false,
+            error: "Token has expired",
+            status: 401,
+        };
+    }
+    // Update last used timestamp (fire-and-forget)
+    store.updateLastUsed(record.id).catch(() => {
+        // Ignore errors updating last_used_at
+    });
+    return {
+        valid: true,
+        token: {
+            id: record.id,
+            user_id: record.user_id,
+            client_id: record.client_id,
+            scope: record.scope,
+        },
+    };
+}
+//# sourceMappingURL=token.js.map

package/dist/auth/token.js.map

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

package/dist/framework/handlers.d.ts

@@ -0,0 +1,14 @@
+import type { CallToolResult } from "@modelcontextprotocol/sdk/types.js";
+import type { EntityConfig, EntityContext } from "./types.js";
+import type { IdOrSlug } from "./resolve.js";
+export interface CrudHandlers<TRepos> {
+    handleList: (ctx: EntityContext<TRepos>, args: Record<string, unknown>) => Promise<CallToolResult>;
+    handleGet: (ctx: EntityContext<TRepos>, args: IdOrSlug) => Promise<CallToolResult>;
+    handleCreate: (ctx: EntityContext<TRepos>, args: Record<string, unknown>) => Promise<CallToolResult>;
+    handleUpdate: (ctx: EntityContext<TRepos>, args: IdOrSlug & Record<string, unknown>) => Promise<CallToolResult>;
+    handleDelete: (ctx: EntityContext<TRepos>, args: IdOrSlug) => Promise<CallToolResult>;
+}
+export declare function createCrudHandlers<T extends {
+    id: string;
+}, TRepos = unknown>(config: EntityConfig<T, TRepos>): CrudHandlers<TRepos>;
+//# sourceMappingURL=handlers.d.ts.map

package/dist/framework/handlers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"handlers.d.ts","sourceRoot":"","sources":["../../src/framework/handlers.ts"],"names":[],"mappings":"AAOA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,oCAAoC,CAAC;AACzE,OAAO,KAAK,EAAE,YAAY,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAC9D,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,cAAc,CAAC;AAK7C,MAAM,WAAW,YAAY,CAAC,MAAM;IAClC,UAAU,EAAE,CACV,GAAG,EAAE,aAAa,CAAC,MAAM,CAAC,EAC1B,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAC1B,OAAO,CAAC,cAAc,CAAC,CAAC;IAC7B,SAAS,EAAE,CACT,GAAG,EAAE,aAAa,CAAC,MAAM,CAAC,EAC1B,IAAI,EAAE,QAAQ,KACX,OAAO,CAAC,cAAc,CAAC,CAAC;IAC7B,YAAY,EAAE,CACZ,GAAG,EAAE,aAAa,CAAC,MAAM,CAAC,EAC1B,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAC1B,OAAO,CAAC,cAAc,CAAC,CAAC;IAC7B,YAAY,EAAE,CACZ,GAAG,EAAE,aAAa,CAAC,MAAM,CAAC,EAC1B,IAAI,EAAE,QAAQ,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KACrC,OAAO,CAAC,cAAc,CAAC,CAAC;IAC7B,YAAY,EAAE,CACZ,GAAG,EAAE,aAAa,CAAC,MAAM,CAAC,EAC1B,IAAI,EAAE,QAAQ,KACX,OAAO,CAAC,cAAc,CAAC,CAAC;CAC9B;AAED,wBAAgB,kBAAkB,CAAC,CAAC,SAAS;IAAE,EAAE,EAAE,MAAM,CAAA;CAAE,EAAE,MAAM,GAAG,OAAO,EAC3E,MAAM,EAAE,YAAY,CAAC,CAAC,EAAE,MAAM,CAAC,GAC9B,YAAY,CAAC,MAAM,CAAC,CA0JtB"}

package/dist/framework/handlers.js

@@ -0,0 +1,110 @@
+// ---------------------------------------------------------------------------
+// Entity-Driven MCP Framework — Generic CRUD Handler Factory
+//
+// Given an EntityConfig, produces 5 typed handler functions:
+// handleList, handleGet, handleCreate, handleUpdate, handleDelete
+// ---------------------------------------------------------------------------
+import { resolveEntity, isResolveError } from "./resolve.js";
+import { ok, error } from "./response.js";
+import { projectFields } from "./projection.js";
+export function createCrudHandlers(config) {
+    const { dataLayer, hooks, projection } = config;
+    const displayName = config.display;
+    // Helper: resolve with entity-specific not-found message
+    async function resolve(ctx, args) {
+        return resolveEntity(args, (id) => dataLayer.getById(ctx, id), dataLayer.getBySlug
+            ? (slug) => dataLayer.getBySlug(ctx, slug)
+            : async () => null, displayName);
+    }
+    // ---- list ----
+    async function handleList(ctx, args) {
+        const result = await dataLayer.list(ctx, args);
+        // Apply projection if configured
+        const items = projection
+            ? result.map((item) => projectFields(item, projection, args.include))
+            : result;
+        return ok(items);
+    }
+    // ---- get ----
+    async function handleGet(ctx, args) {
+        const resolved = await resolve(ctx, args);
+        if (isResolveError(resolved))
+            return error(resolved.error);
+        return ok(resolved);
+    }
+    // ---- create ----
+    async function handleCreate(ctx, args) {
+        if (!dataLayer.create) {
+            return error(`${displayName} does not support creation`);
+        }
+        // Apply beforeCreate hook if defined
+        const input = hooks?.beforeCreate
+            ? await hooks.beforeCreate(ctx, args)
+            : args;
+        const entity = await dataLayer.create(ctx, input);
+        // Apply afterCreate hook (best-effort)
+        if (hooks?.afterCreate) {
+            try {
+                await hooks.afterCreate(ctx, entity);
+            }
+            catch (err) {
+                console.error(`[MCP] ${displayName} afterCreate hook failed (best-effort):`, err);
+            }
+        }
+        return ok(entity);
+    }
+    // ---- update ----
+    async function handleUpdate(ctx, args) {
+        if (!dataLayer.update) {
+            return error(`${displayName} does not support updates`);
+        }
+        const resolved = await resolve(ctx, args);
+        if (isResolveError(resolved))
+            return error(resolved.error);
+        // Strip MCP identifier fields before any hook sees the args
+        const { id: _id, slug: _slug, ...businessFields } = args;
+        // Apply beforeUpdate hook if defined
+        const input = hooks?.beforeUpdate
+            ? await hooks.beforeUpdate(ctx, resolved.id, businessFields, resolved)
+            : businessFields;
+        const updated = await dataLayer.update(ctx, resolved.id, input);
+        if (!updated)
+            return error(`${displayName} not found: ${resolved.id}`);
+        // Apply afterUpdate hook (best-effort)
+        if (hooks?.afterUpdate) {
+            try {
+                await hooks.afterUpdate(ctx, resolved.id, businessFields, updated);
+            }
+            catch (err) {
+                console.error(`[MCP] ${displayName} afterUpdate hook failed (best-effort):`, err);
+            }
+        }
+        return ok(updated);
+    }
+    // ---- delete ----
+    async function handleDelete(ctx, args) {
+        if (!dataLayer.delete) {
+            return error(`${displayName} does not support deletion`);
+        }
+        const resolved = await resolve(ctx, args);
+        if (isResolveError(resolved))
+            return error(resolved.error);
+        // Apply beforeDelete hook if defined
+        if (hooks?.beforeDelete) {
+            await hooks.beforeDelete(ctx, resolved.id, resolved);
+        }
+        await dataLayer.delete(ctx, resolved.id);
+        // Apply afterDelete hook (best-effort)
+        if (hooks?.afterDelete) {
+            try {
+                await hooks.afterDelete(ctx, resolved.id);
+            }
+            catch (err) {
+                console.error(`[MCP] ${displayName} afterDelete hook failed (best-effort):`, err);
+            }
+        }
+        return ok({ deleted: true });
+    }
+    return { handleList, handleGet, handleCreate, handleUpdate, handleDelete };
+}
+//# sourceMappingURL=handlers.js.map

package/dist/framework/handlers.js.map

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

package/dist/framework/index.d.ts

@@ -0,0 +1,7 @@
+export { ok, error } from "./response.js";
+export { projectFields } from "./projection.js";
+export { validateIdOrSlug, resolveEntity, isResolveError, type IdOrSlug, type ResolveResult, } from "./resolve.js";
+export { createCrudHandlers, type CrudHandlers } from "./handlers.js";
+export { registerEntityTools, registerCustomTool } from "./register.js";
+export type { ProjectionConfig, EntityContext, DataLayer, EntityHooks, EntitySchemas, EntityDescriptions, EntityConfig, ToolHandler, CustomToolConfig, } from "./types.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/framework/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/framework/index.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,MAAM,eAAe,CAAC;AAC1C,OAAO,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AAChD,OAAO,EACL,gBAAgB,EAChB,aAAa,EACb,cAAc,EACd,KAAK,QAAQ,EACb,KAAK,aAAa,GACnB,MAAM,cAAc,CAAC;AACtB,OAAO,EAAE,kBAAkB,EAAE,KAAK,YAAY,EAAE,MAAM,eAAe,CAAC;AACtE,OAAO,EAAE,mBAAmB,EAAE,kBAAkB,EAAE,MAAM,eAAe,CAAC;AACxE,YAAY,EACV,gBAAgB,EAChB,aAAa,EACb,SAAS,EACT,WAAW,EACX,aAAa,EACb,kBAAkB,EAClB,YAAY,EACZ,WAAW,EACX,gBAAgB,GACjB,MAAM,YAAY,CAAC"}

package/dist/framework/index.js

@@ -0,0 +1,7 @@
+// Framework exports
+export { ok, error } from "./response.js";
+export { projectFields } from "./projection.js";
+export { validateIdOrSlug, resolveEntity, isResolveError, } from "./resolve.js";
+export { createCrudHandlers } from "./handlers.js";
+export { registerEntityTools, registerCustomTool } from "./register.js";
+//# sourceMappingURL=index.js.map

package/dist/framework/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/framework/index.ts"],"names":[],"mappings":"AAAA,oBAAoB;AACpB,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,MAAM,eAAe,CAAC;AAC1C,OAAO,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AAChD,OAAO,EACL,gBAAgB,EAChB,aAAa,EACb,cAAc,GAGf,MAAM,cAAc,CAAC;AACtB,OAAO,EAAE,kBAAkB,EAAqB,MAAM,eAAe,CAAC;AACtE,OAAO,EAAE,mBAAmB,EAAE,kBAAkB,EAAE,MAAM,eAAe,CAAC"}

package/dist/framework/projection.d.ts

@@ -0,0 +1,10 @@
+import type { ProjectionConfig } from "./types.js";
+/**
+ * Remove omitted fields from a record, unless included via named groups.
+ *
+ * - Default: omit all fields in `config.omit`
+ * - If `include` contains a group name, restore those fields
+ * - If `include` contains `"full"`, return the record unchanged
+ */
+export declare function projectFields<T extends Record<string, unknown>>(record: T, config: ProjectionConfig, include?: string[]): Record<string, unknown>;
+//# sourceMappingURL=projection.d.ts.map

package/dist/framework/projection.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"projection.d.ts","sourceRoot":"","sources":["../../src/framework/projection.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AAEnD;;;;;;GAMG;AACH,wBAAgB,aAAa,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC7D,MAAM,EAAE,CAAC,EACT,MAAM,EAAE,gBAAgB,EACxB,OAAO,CAAC,EAAE,MAAM,EAAE,GACjB,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAezB"}

package/dist/framework/projection.js

@@ -0,0 +1,21 @@
+// ---------------------------------------------------------------------------
+// Entity-Driven MCP Framework — Field Projection Engine
+// ---------------------------------------------------------------------------
+/**
+ * Remove omitted fields from a record, unless included via named groups.
+ *
+ * - Default: omit all fields in `config.omit`
+ * - If `include` contains a group name, restore those fields
+ * - If `include` contains `"full"`, return the record unchanged
+ */
+export function projectFields(record, config, include) {
+    // "full" bypass — return everything
+    if (include?.includes("full"))
+        return { ...record };
+    // Resolve which fields should be restored from omit list
+    const included = new Set((include ?? []).flatMap((key) => config.groups[key] ?? []));
+    // Build omit set (fields to drop minus included overrides)
+    const omitSet = new Set(config.omit.filter((k) => !included.has(k)));
+    return Object.fromEntries(Object.entries(record).filter(([key]) => !omitSet.has(key)));
+}
+//# sourceMappingURL=projection.js.map

package/dist/framework/projection.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"projection.js","sourceRoot":"","sources":["../../src/framework/projection.ts"],"names":[],"mappings":"AAAA,8EAA8E;AAC9E,wDAAwD;AACxD,8EAA8E;AAI9E;;;;;;GAMG;AACH,MAAM,UAAU,aAAa,CAC3B,MAAS,EACT,MAAwB,EACxB,OAAkB;IAElB,oCAAoC;IACpC,IAAI,OAAO,EAAE,QAAQ,CAAC,MAAM,CAAC;QAAE,OAAO,EAAE,GAAG,MAAM,EAAE,CAAC;IAEpD,yDAAyD;IACzD,MAAM,QAAQ,GAAG,IAAI,GAAG,CACtB,CAAC,OAAO,IAAI,EAAE,CAAC,CAAC,OAAO,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,MAAM,CAAC,MAAM,CAAC,GAAG,CAAC,IAAI,EAAE,CAAC,CAC3D,CAAC;IAEF,2DAA2D;IAC3D,MAAM,OAAO,GAAG,IAAI,GAAG,CAAC,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;IAErE,OAAO,MAAM,CAAC,WAAW,CACvB,MAAM,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,GAAG,CAAC,EAAE,EAAE,CAAC,CAAC,OAAO,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC,CAC5D,CAAC;AACJ,CAAC"}

package/dist/framework/register.d.ts

@@ -0,0 +1,16 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import type { EntityConfig, EntityContext, CustomToolConfig } from "./types.js";
+/**
+ * Register CRUD tools for an entity on an MCP server.
+ *
+ * Generates 5 tools: list_*, get_*, create_*, update_*, delete_*
+ * where * is the entity's plural name.
+ */
+export declare function registerEntityTools<T extends {
+    id: string;
+}, TRepos = unknown>(server: McpServer, config: EntityConfig<T, TRepos>, ctx: EntityContext<TRepos>): void;
+/**
+ * Register a custom tool on an MCP server.
+ */
+export declare function registerCustomTool<TRepos = unknown>(server: McpServer, tool: CustomToolConfig<TRepos>, ctx: EntityContext<TRepos>): void;
+//# sourceMappingURL=register.d.ts.map

package/dist/framework/register.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"register.d.ts","sourceRoot":"","sources":["../../src/framework/register.ts"],"names":[],"mappings":"AAOA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AAEzE,OAAO,KAAK,EAAE,YAAY,EAAE,aAAa,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AAGhF;;;;;GAKG;AACH,wBAAgB,mBAAmB,CAAC,CAAC,SAAS;IAAE,EAAE,EAAE,MAAM,CAAA;CAAE,EAAE,MAAM,GAAG,OAAO,EAC5E,MAAM,EAAE,SAAS,EACjB,MAAM,EAAE,YAAY,CAAC,CAAC,EAAE,MAAM,CAAC,EAC/B,GAAG,EAAE,aAAa,CAAC,MAAM,CAAC,GACzB,IAAI,CAyEN;AAED;;GAEG;AACH,wBAAgB,kBAAkB,CAAC,MAAM,GAAG,OAAO,EACjD,MAAM,EAAE,SAAS,EACjB,IAAI,EAAE,gBAAgB,CAAC,MAAM,CAAC,EAC9B,GAAG,EAAE,aAAa,CAAC,MAAM,CAAC,GACzB,IAAI,CAQN"}

package/dist/framework/register.js

@@ -0,0 +1,70 @@
+// ---------------------------------------------------------------------------
+// Entity-Driven MCP Framework — Tool Registration Engine
+//
+// Reads an EntityConfig and registers all CRUD tools + extra tools on an
+// McpServer instance. This is the bridge between the framework and the SDK.
+// ---------------------------------------------------------------------------
+import { z } from "zod";
+import { createCrudHandlers } from "./handlers.js";
+/**
+ * Register CRUD tools for an entity on an MCP server.
+ *
+ * Generates 5 tools: list_*, get_*, create_*, update_*, delete_*
+ * where * is the entity's plural name.
+ */
+export function registerEntityTools(server, config, ctx) {
+    const plural = config.plural ?? config.name + "s";
+    const handlers = createCrudHandlers(config);
+    // ---- list ----
+    server.tool(`list_${plural}`, config.descriptions?.list ?? `List all ${plural}.`, {
+        ...(config.schemas?.list ?? {}),
+        ...(config.projection
+            ? {
+                include: z
+                    .array(z.string())
+                    .optional()
+                    .describe("Opt-in fields excluded by default. Use 'full' for all fields."),
+            }
+            : {}),
+    }, 
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    ((args) => handlers.handleList(ctx, args)));
+    // ---- get ----
+    server.tool(`get_${config.name}`, config.descriptions?.get ??
+        `Get a single ${config.display} by id or slug (exactly one required).`, { id: z.string().optional(), slug: z.string().optional() }, 
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    ((args) => handlers.handleGet(ctx, args)));
+    // ---- create (only if dataLayer.create exists) ----
+    if (config.dataLayer.create) {
+        server.tool(`create_${config.name}`, config.descriptions?.create ?? `Create a new ${config.display}.`, config.schemas?.create ?? {}, 
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        ((args) => handlers.handleCreate(ctx, args)));
+    }
+    // ---- update (only if dataLayer.update exists) ----
+    if (config.dataLayer.update) {
+        server.tool(`update_${config.name}`, config.descriptions?.update ??
+            `Update an existing ${config.display} by id or slug (exactly one required).`, {
+            id: z.string().optional(),
+            slug: z.string().optional(),
+            ...(config.schemas?.update ?? {}),
+        }, 
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        ((args) => handlers.handleUpdate(ctx, args)));
+    }
+    // ---- delete (only if dataLayer.delete exists) ----
+    if (config.dataLayer.delete) {
+        server.tool(`delete_${config.name}`, config.descriptions?.delete ??
+            `Delete a ${config.display} by id or slug (exactly one required). Irreversible.`, { id: z.string().optional(), slug: z.string().optional() }, 
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        ((args) => handlers.handleDelete(ctx, args)));
+    }
+}
+/**
+ * Register a custom tool on an MCP server.
+ */
+export function registerCustomTool(server, tool, ctx) {
+    server.tool(tool.name, tool.description, tool.schema.shape, 
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    ((args) => tool.handler(ctx, args)));
+}
+//# sourceMappingURL=register.js.map

package/dist/framework/register.js.map

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

package/dist/framework/resolve.d.ts

@@ -0,0 +1,39 @@
+export type IdOrSlug = {
+    id?: string;
+    slug?: string;
+};
+export type ResolveResult = {
+    type: "id";
+    value: string;
+} | {
+    type: "slug";
+    value: string;
+} | {
+    error: string;
+};
+/**
+ * Validate that exactly one of id or slug is provided.
+ * Both → error. Neither → error.
+ */
+export declare function validateIdOrSlug(args: IdOrSlug): ResolveResult;
+/**
+ * Resolve an entity by id or slug. Returns the entity or an error object.
+ * Decoupled from specific entities — takes lookup functions as parameters.
+ *
+ * @param args - Object with id or slug
+ * @param getById - Function to lookup by id
+ * @param getBySlug - Function to lookup by slug
+ * @param displayName - Human-readable name for error messages
+ */
+export declare function resolveEntity<T>(args: IdOrSlug, getById: (id: string) => Promise<T | null>, getBySlug: (slug: string) => Promise<T | null>, displayName?: string): Promise<T | {
+    error: string;
+}>;
+/**
+ * Type guard to check if a resolve result is an error.
+ */
+export declare function isResolveError<T>(result: T | {
+    error: string;
+}): result is {
+    error: string;
+};
+//# sourceMappingURL=resolve.d.ts.map

package/dist/framework/resolve.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"resolve.d.ts","sourceRoot":"","sources":["../../src/framework/resolve.ts"],"names":[],"mappings":"AAIA,MAAM,MAAM,QAAQ,GAAG;IAAE,EAAE,CAAC,EAAE,MAAM,CAAC;IAAC,IAAI,CAAC,EAAE,MAAM,CAAA;CAAE,CAAC;AAEtD,MAAM,MAAM,aAAa,GACrB;IAAE,IAAI,EAAE,IAAI,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,GAC7B;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,GAC/B;IAAE,KAAK,EAAE,MAAM,CAAA;CAAE,CAAC;AAEtB;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,QAAQ,GAAG,aAAa,CAM9D;AAED;;;;;;;;GAQG;AACH,wBAAsB,aAAa,CAAC,CAAC,EACnC,IAAI,EAAE,QAAQ,EACd,OAAO,EAAE,CAAC,EAAE,EAAE,MAAM,KAAK,OAAO,CAAC,CAAC,GAAG,IAAI,CAAC,EAC1C,SAAS,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC,CAAC,GAAG,IAAI,CAAC,EAC9C,WAAW,CAAC,EAAE,MAAM,GACnB,OAAO,CAAC,CAAC,GAAG;IAAE,KAAK,EAAE,MAAM,CAAA;CAAE,CAAC,CAUhC;AAED;;GAEG;AACH,wBAAgB,cAAc,CAAC,CAAC,EAC9B,MAAM,EAAE,CAAC,GAAG;IAAE,KAAK,EAAE,MAAM,CAAA;CAAE,GAC5B,MAAM,IAAI;IAAE,KAAK,EAAE,MAAM,CAAA;CAAE,CAO7B"}

package/dist/framework/resolve.js

@@ -0,0 +1,46 @@
+// ---------------------------------------------------------------------------
+// Entity-Driven MCP Framework — ID/Slug Resolution
+// ---------------------------------------------------------------------------
+/**
+ * Validate that exactly one of id or slug is provided.
+ * Both → error. Neither → error.
+ */
+export function validateIdOrSlug(args) {
+    if (args.id && args.slug)
+        return { error: "Provide either id or slug, not both." };
+    if (args.id)
+        return { type: "id", value: args.id };
+    if (args.slug)
+        return { type: "slug", value: args.slug };
+    return { error: "Either id or slug is required." };
+}
+/**
+ * Resolve an entity by id or slug. Returns the entity or an error object.
+ * Decoupled from specific entities — takes lookup functions as parameters.
+ *
+ * @param args - Object with id or slug
+ * @param getById - Function to lookup by id
+ * @param getBySlug - Function to lookup by slug
+ * @param displayName - Human-readable name for error messages
+ */
+export async function resolveEntity(args, getById, getBySlug, displayName) {
+    const v = validateIdOrSlug(args);
+    if ("error" in v)
+        return v;
+    const entity = v.type === "id" ? await getById(v.value) : await getBySlug(v.value);
+    if (!entity) {
+        const label = displayName ?? "Entity";
+        return { error: `${label} not found: ${v.value}` };
+    }
+    return entity;
+}
+/**
+ * Type guard to check if a resolve result is an error.
+ */
+export function isResolveError(result) {
+    return (typeof result === "object" &&
+        result !== null &&
+        "error" in result &&
+        typeof result.error === "string");
+}
+//# sourceMappingURL=resolve.js.map

package/dist/framework/resolve.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"resolve.js","sourceRoot":"","sources":["../../src/framework/resolve.ts"],"names":[],"mappings":"AAAA,8EAA8E;AAC9E,mDAAmD;AACnD,8EAA8E;AAS9E;;;GAGG;AACH,MAAM,UAAU,gBAAgB,CAAC,IAAc;IAC7C,IAAI,IAAI,CAAC,EAAE,IAAI,IAAI,CAAC,IAAI;QACtB,OAAO,EAAE,KAAK,EAAE,sCAAsC,EAAE,CAAC;IAC3D,IAAI,IAAI,CAAC,EAAE;QAAE,OAAO,EAAE,IAAI,EAAE,IAAI,EAAE,KAAK,EAAE,IAAI,CAAC,EAAE,EAAE,CAAC;IACnD,IAAI,IAAI,CAAC,IAAI;QAAE,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,IAAI,CAAC,IAAI,EAAE,CAAC;IACzD,OAAO,EAAE,KAAK,EAAE,gCAAgC,EAAE,CAAC;AACrD,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,CAAC,KAAK,UAAU,aAAa,CACjC,IAAc,EACd,OAA0C,EAC1C,SAA8C,EAC9C,WAAoB;IAEpB,MAAM,CAAC,GAAG,gBAAgB,CAAC,IAAI,CAAC,CAAC;IACjC,IAAI,OAAO,IAAI,CAAC;QAAE,OAAO,CAAC,CAAC;IAC3B,MAAM,MAAM,GACV,CAAC,CAAC,IAAI,KAAK,IAAI,CAAC,CAAC,CAAC,MAAM,OAAO,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,MAAM,SAAS,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC;IACtE,IAAI,CAAC,MAAM,EAAE,CAAC;QACZ,MAAM,KAAK,GAAG,WAAW,IAAI,QAAQ,CAAC;QACtC,OAAO,EAAE,KAAK,EAAE,GAAG,KAAK,eAAe,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC;IACrD,CAAC;IACD,OAAO,MAAM,CAAC;AAChB,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,cAAc,CAC5B,MAA6B;IAE7B,OAAO,CACL,OAAO,MAAM,KAAK,QAAQ;QAC1B,MAAM,KAAK,IAAI;QACf,OAAO,IAAI,MAAM;QACjB,OAAQ,MAA6B,CAAC,KAAK,KAAK,QAAQ,CACzD,CAAC;AACJ,CAAC"}

package/dist/framework/response.d.ts

@@ -0,0 +1,6 @@
+import type { CallToolResult } from "@modelcontextprotocol/sdk/types.js";
+/** Build a successful MCP tool response with JSON-serialized data. */
+export declare function ok(data: unknown): CallToolResult;
+/** Build an error MCP tool response. */
+export declare function error(message: string): CallToolResult;
+//# sourceMappingURL=response.d.ts.map

package/dist/framework/response.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"response.d.ts","sourceRoot":"","sources":["../../src/framework/response.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,oCAAoC,CAAC;AAEzE,sEAAsE;AACtE,wBAAgB,EAAE,CAAC,IAAI,EAAE,OAAO,GAAG,cAAc,CAIhD;AAED,wCAAwC;AACxC,wBAAgB,KAAK,CAAC,OAAO,EAAE,MAAM,GAAG,cAAc,CAKrD"}

package/dist/framework/response.js

@@ -0,0 +1,17 @@
+// ---------------------------------------------------------------------------
+// Entity-Driven MCP Framework — MCP Response Builders
+// ---------------------------------------------------------------------------
+/** Build a successful MCP tool response with JSON-serialized data. */
+export function ok(data) {
+    return {
+        content: [{ type: "text", text: JSON.stringify(data, null, 2) }],
+    };
+}
+/** Build an error MCP tool response. */
+export function error(message) {
+    return {
+        content: [{ type: "text", text: message }],
+        isError: true,
+    };
+}
+//# sourceMappingURL=response.js.map

package/dist/framework/response.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"response.js","sourceRoot":"","sources":["../../src/framework/response.ts"],"names":[],"mappings":"AAAA,8EAA8E;AAC9E,sDAAsD;AACtD,8EAA8E;AAI9E,sEAAsE;AACtE,MAAM,UAAU,EAAE,CAAC,IAAa;IAC9B,OAAO;QACL,OAAO,EAAE,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,IAAI,EAAE,IAAI,EAAE,CAAC,CAAC,EAAE,CAAC;KACjE,CAAC;AACJ,CAAC;AAED,wCAAwC;AACxC,MAAM,UAAU,KAAK,CAAC,OAAe;IACnC,OAAO;QACL,OAAO,EAAE,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,OAAO,EAAE,CAAC;QAC1C,OAAO,EAAE,IAAI;KACd,CAAC;AACJ,CAAC"}

package/dist/framework/types.d.ts

@@ -0,0 +1,85 @@
+import type { CallToolResult } from "@modelcontextprotocol/sdk/types.js";
+import type { ZodTypeAny, z } from "zod";
+export interface ProjectionConfig {
+    /** Fields to omit from list responses by default. */
+    omit: string[];
+    /** Named groups of omitted fields. Key = group name, value = field names. */
+    groups: Record<string, string[]>;
+}
+/**
+ * Context passed to data layer functions.
+ * Generic to allow different repo structures per project.
+ */
+export interface EntityContext<TRepos = unknown> {
+    repos: TRepos;
+}
+/**
+ * Data layer interface for an entity.
+ * All methods receive the context and return promises.
+ */
+export interface DataLayer<T, TRepos = unknown> {
+    list: (ctx: EntityContext<TRepos>, opts: Record<string, unknown>) => Promise<T[]>;
+    getById: (ctx: EntityContext<TRepos>, id: string) => Promise<T | null>;
+    getBySlug?: (ctx: EntityContext<TRepos>, slug: string) => Promise<T | null>;
+    create?: (ctx: EntityContext<TRepos>, input: Record<string, unknown>) => Promise<T>;
+    update?: (ctx: EntityContext<TRepos>, id: string, input: Record<string, unknown>) => Promise<T | null>;
+    delete?: (ctx: EntityContext<TRepos>, id: string) => Promise<boolean>;
+}
+/**
+ * Lifecycle hooks for entity operations.
+ */
+export interface EntityHooks<T, TRepos = unknown> {
+    beforeCreate?: (ctx: EntityContext<TRepos>, input: Record<string, unknown>) => Promise<Record<string, unknown>>;
+    afterCreate?: (ctx: EntityContext<TRepos>, result: T) => Promise<void>;
+    beforeUpdate?: (ctx: EntityContext<TRepos>, id: string, input: Record<string, unknown>, existing: T) => Promise<Record<string, unknown>>;
+    afterUpdate?: (ctx: EntityContext<TRepos>, id: string, input: Record<string, unknown>, result: T) => Promise<void>;
+    beforeDelete?: (ctx: EntityContext<TRepos>, id: string, existing: T) => Promise<void>;
+    afterDelete?: (ctx: EntityContext<TRepos>, id: string) => Promise<void>;
+}
+/**
+ * Schema definitions for entity operations.
+ */
+export interface EntitySchemas {
+    list?: Record<string, ZodTypeAny>;
+    create?: Record<string, ZodTypeAny>;
+    update?: Record<string, ZodTypeAny>;
+}
+/**
+ * Description text for generated tools.
+ */
+export interface EntityDescriptions {
+    list?: string;
+    get?: string;
+    create?: string;
+    update?: string;
+    delete?: string;
+}
+/**
+ * Full entity configuration.
+ */
+export interface EntityConfig<T, TRepos = unknown> {
+    /** Singular name (e.g., "product") */
+    name: string;
+    /** Human-readable display name (e.g., "理财产品") */
+    display: string;
+    /** Plural name for list operations (e.g., "products") */
+    plural: string;
+    /** Data access layer */
+    dataLayer: DataLayer<T, TRepos>;
+    /** Zod schemas for input validation */
+    schemas?: EntitySchemas;
+    /** Tool descriptions for MCP */
+    descriptions?: EntityDescriptions;
+    /** Field projection configuration */
+    projection?: ProjectionConfig;
+    /** Lifecycle hooks */
+    hooks?: EntityHooks<T, TRepos>;
+}
+export type ToolHandler<TRepos = unknown> = (ctx: EntityContext<TRepos>, args: Record<string, unknown>) => Promise<CallToolResult>;
+export interface CustomToolConfig<TRepos = unknown> {
+    name: string;
+    description: string;
+    schema: z.ZodObject<Record<string, ZodTypeAny>>;
+    handler: ToolHandler<TRepos>;
+}
+//# sourceMappingURL=types.d.ts.map