@faapi/schema 0.0.0-canary.0

package/dist/index.d.ts

@@ -0,0 +1,18 @@
+import { PluginContext } from '@faapi/faapi';
+
+/**
+ * faapi 插件入口
+ *
+ * 在 faapi.config.ts 中声明：
+ * ```ts
+ * export default {
+ *   plugins: ['@faapi/schema'],
+ * } satisfies FaapiConfig;
+ * ```
+ */
+declare const _default: {
+    name: string;
+    setup(ctx: PluginContext): void;
+};
+
+export { _default as default };

package/dist/index.js

@@ -0,0 +1,180 @@
+// src/schemaServer.ts
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { z } from "zod";
+
+// src/routeSchema.ts
+import path from "path";
+import {
+  getSchemaProperties,
+  getInputTypeForMethod
+} from "@faapi/faapi";
+function buildRouteSchemas(routes, rootDir) {
+  return routes.map((route) => {
+    const absoluteFilePath = path.resolve(rootDir, route.filePath);
+    const inputs = extractInputSchemas(absoluteFilePath, route.method, route);
+    return {
+      method: route.method,
+      path: route.urlPath,
+      filePath: route.filePath,
+      isDynamic: route.isDynamic,
+      inputs
+    };
+  });
+}
+function extractInputSchemas(filePath, method, route) {
+  const inputs = [];
+  const inputType = getInputTypeForMethod(method);
+  const schema = getSchemaProperties(filePath, method, inputType);
+  if (schema) {
+    inputs.push({
+      source: inputType,
+      schemaName: schema.schemaName,
+      properties: schema.properties
+    });
+  } else {
+    inputs.push({
+      source: inputType,
+      schemaName: null,
+      properties: []
+    });
+  }
+  if (route.isDynamic && route.paramNames.length > 0) {
+    const paramsSchema = getSchemaProperties(filePath, method, "params");
+    const paramsProps = paramsSchema && paramsSchema.schemaName ? paramsSchema.properties : route.paramNames.map((name) => ({
+      name,
+      type: "string",
+      required: true
+    }));
+    inputs.push({
+      source: "params",
+      schemaName: paramsSchema?.schemaName ?? null,
+      properties: paramsProps
+    });
+  }
+  return inputs;
+}
+
+// src/schemaServer.ts
+function isSchemaEnabled() {
+  const envValue = process.env.FAAPI_SCHEMA;
+  if (envValue === "1" || envValue === "true") return true;
+  if (envValue === "0" || envValue === "false") return false;
+  return process.env.NODE_ENV !== "production";
+}
+function createSchemaServer(routes, rootDir) {
+  const server = new McpServer({
+    name: "faapi-schema",
+    version: "0.0.1"
+  });
+  let cachedSchemas = null;
+  function getSchemas() {
+    if (!cachedSchemas) {
+      cachedSchemas = buildRouteSchemas(routes, rootDir);
+    }
+    return cachedSchemas;
+  }
+  server.tool(
+    "list_routes",
+    "\u5217\u51FA\u5F53\u524D faapi \u5E94\u7528\u7684\u6240\u6709 API \u8DEF\u7531\uFF0C\u5305\u62EC\u65B9\u6CD5\u3001\u8DEF\u5F84\u3001\u662F\u5426\u52A8\u6001\u8DEF\u7531",
+    {},
+    () => {
+      const schemas = getSchemas();
+      const routesList = schemas.map((r) => ({
+        method: r.method,
+        path: r.path,
+        isDynamic: r.isDynamic,
+        filePath: r.filePath
+      }));
+      return {
+        content: [
+          {
+            type: "text",
+            text: JSON.stringify(routesList, null, 2)
+          }
+        ]
+      };
+    }
+  );
+  server.tool(
+    "get_route_schema",
+    "\u83B7\u53D6\u6307\u5B9A\u8DEF\u7531\u7684\u8BE6\u7EC6\u63A5\u53E3\u4FE1\u606F\uFF0C\u5305\u62EC\u8F93\u5165\u53C2\u6570\u7684\u540D\u79F0\u3001\u7C7B\u578B\u3001\u662F\u5426\u5FC5\u586B",
+    {
+      method: z.string().describe("HTTP \u65B9\u6CD5\uFF0C\u5982 GET\u3001POST"),
+      path: z.string().describe("\u8DEF\u7531\u8DEF\u5F84\uFF0C\u5982 /auth/login")
+    },
+    ({ method, path: path2 }) => {
+      const schemas = getSchemas();
+      const route = schemas.find((r) => r.method === method.toUpperCase() && r.path === path2);
+      if (!route) {
+        return {
+          content: [
+            {
+              type: "text",
+              text: JSON.stringify({ error: `\u672A\u627E\u5230\u8DEF\u7531 ${method.toUpperCase()} ${path2}` })
+            }
+          ]
+        };
+      }
+      return {
+        content: [
+          {
+            type: "text",
+            text: JSON.stringify(route, null, 2)
+          }
+        ]
+      };
+    }
+  );
+  server.tool(
+    "get_api_schema",
+    "\u83B7\u53D6\u5F53\u524D\u5E94\u7528\u6240\u6709\u63A5\u53E3\u7684\u5B8C\u6574 schema\uFF0C\u7C7B\u4F3C OpenAPI \u89C4\u8303\uFF0C\u5305\u542B\u6BCF\u4E2A\u8DEF\u7531\u7684\u8F93\u5165\u53C2\u6570\u5B9A\u4E49",
+    {},
+    () => {
+      const schemas = getSchemas();
+      const apiSchema = {};
+      for (const route of schemas) {
+        const key = `${route.method} ${route.path}`;
+        apiSchema[key] = {
+          method: route.method,
+          path: route.path,
+          isDynamic: route.isDynamic,
+          inputs: route.inputs.map((input) => ({
+            source: input.source,
+            schemaName: input.schemaName,
+            properties: input.properties
+          }))
+        };
+      }
+      return {
+        content: [
+          {
+            type: "text",
+            text: JSON.stringify(apiSchema, null, 2)
+          }
+        ]
+      };
+    }
+  );
+  return server;
+}
+async function startSchemaServer(routes, rootDir) {
+  const server = createSchemaServer(routes, rootDir);
+  const transport = new StdioServerTransport();
+  await server.connect(transport);
+}
+var schemaServer_default = {
+  name: "@faapi/schema",
+  setup(ctx) {
+    if (!isSchemaEnabled()) {
+      console.log("- Schema server disabled (FAAPI_SCHEMA=0 or production mode)");
+      return;
+    }
+    console.log("- Schema server enabled (stdio)");
+    void startSchemaServer(ctx.routes, ctx.rootDir);
+  }
+};
+export {
+  schemaServer_default as default
+};
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/schemaServer.ts","../src/routeSchema.ts"],"sourcesContent":["import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';\nimport { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';\nimport { z } from 'zod';\nimport type { RouteManifest, RouteInfo, FaapiPlugin, PluginContext } from '@faapi/faapi';\nimport { buildRouteSchemas } from './routeSchema.js';\n\n/**\n * 判断 schema server 是否应该启用\n * - FAAPI_SCHEMA=1 强制开启\n * - FAAPI_SCHEMA=0 强制关闭\n * - 未设置时：开发环境默认开启，生产环境默认关闭\n */\nexport function isSchemaEnabled(): boolean {\n  const envValue = process.env.FAAPI_SCHEMA;\n  if (envValue === '1' || envValue === 'true') return true;\n  if (envValue === '0' || envValue === 'false') return false;\n  // 未设置时根据 NODE_ENV 判断\n  return process.env.NODE_ENV !== 'production';\n}\n\n/**\n * 创建 faapi Schema Server\n * 通过 MCP 协议暴露路由信息供 LLM 查询\n */\nexport function createSchemaServer(routes: RouteManifest, rootDir: string): McpServer {\n  const server = new McpServer({\n    name: 'faapi-schema',\n    version: '0.0.1',\n  });\n\n  // 缓存 route schemas\n  let cachedSchemas: RouteInfo[] | null = null;\n\n  function getSchemas(): RouteInfo[] {\n    if (!cachedSchemas) {\n      cachedSchemas = buildRouteSchemas(routes, rootDir);\n    }\n    return cachedSchemas;\n  }\n\n  // Tool: 列出所有路由\n  server.tool(\n    'list_routes',\n    '列出当前 faapi 应用的所有 API 路由，包括方法、路径、是否动态路由',\n    {},\n    () => {\n      const schemas = getSchemas();\n      const routesList = schemas.map((r) => ({\n        method: r.method,\n        path: r.path,\n        isDynamic: r.isDynamic,\n        filePath: r.filePath,\n      }));\n      return {\n        content: [\n          {\n            type: 'text' as const,\n            text: JSON.stringify(routesList, null, 2),\n          },\n        ],\n      };\n    },\n  );\n\n  // Tool: 获取单个路由的详细 schema\n  server.tool(\n    'get_route_schema',\n    '获取指定路由的详细接口信息，包括输入参数的名称、类型、是否必填',\n    {\n      method: z.string().describe('HTTP 方法，如 GET、POST'),\n      path: z.string().describe('路由路径，如 /auth/login'),\n    },\n    ({ method, path }) => {\n      const schemas = getSchemas();\n      const route = schemas.find((r) => r.method === method.toUpperCase() && r.path === path);\n\n      if (!route) {\n        return {\n          content: [\n            {\n              type: 'text' as const,\n              text: JSON.stringify({ error: `未找到路由 ${method.toUpperCase()} ${path}` }),\n            },\n          ],\n        };\n      }\n\n      return {\n        content: [\n          {\n            type: 'text' as const,\n            text: JSON.stringify(route, null, 2),\n          },\n        ],\n      };\n    },\n  );\n\n  // Tool: 获取所有路由的完整 schema（类似 OpenAPI）\n  server.tool(\n    'get_api_schema',\n    '获取当前应用所有接口的完整 schema，类似 OpenAPI 规范，包含每个路由的输入参数定义',\n    {},\n    () => {\n      const schemas = getSchemas();\n      const apiSchema: Record<string, unknown> = {};\n\n      for (const route of schemas) {\n        const key = `${route.method} ${route.path}`;\n        apiSchema[key] = {\n          method: route.method,\n          path: route.path,\n          isDynamic: route.isDynamic,\n          inputs: route.inputs.map((input) => ({\n            source: input.source,\n            schemaName: input.schemaName,\n            properties: input.properties,\n          })),\n        };\n      }\n\n      return {\n        content: [\n          {\n            type: 'text' as const,\n            text: JSON.stringify(apiSchema, null, 2),\n          },\n        ],\n      };\n    },\n  );\n\n  return server;\n}\n\n/**\n * 启动 Schema Server（stdio 模式）\n */\nexport async function startSchemaServer(routes: RouteManifest, rootDir: string): Promise<void> {\n  const server = createSchemaServer(routes, rootDir);\n  const transport = new StdioServerTransport();\n  await server.connect(transport);\n}\n\n/**\n * faapi 插件入口\n *\n * 在 faapi.config.ts 中声明：\n * ```ts\n * export default {\n *   plugins: ['@faapi/schema'],\n * } satisfies FaapiConfig;\n * ```\n */\nexport default {\n  name: '@faapi/schema',\n  setup(ctx: PluginContext) {\n    if (!isSchemaEnabled()) {\n      console.log('- Schema server disabled (FAAPI_SCHEMA=0 or production mode)');\n      return;\n    }\n    console.log('- Schema server enabled (stdio)');\n    // startSchemaServer 是异步的，但不阻塞启动流程\n    void startSchemaServer(ctx.routes, ctx.rootDir);\n  },\n} satisfies FaapiPlugin;\n","import path from 'node:path';\nimport {\n  getSchemaProperties,\n  getInputTypeForMethod,\n  type RouteManifest,\n  type RouteInfo,\n  type RouteInputSchema,\n} from '@faapi/faapi';\n\n/**\n * 从路由清单生成接口描述信息\n *\n * 复用主包 schemaRegistry 已有的类型提取结果，避免重复 AST 分析。\n *\n * @param routes 路由清单\n * @param rootDir 根目录\n */\nexport function buildRouteSchemas(routes: RouteManifest, rootDir: string): RouteInfo[] {\n  return routes.map((route) => {\n    const absoluteFilePath = path.resolve(rootDir, route.filePath);\n    const inputs = extractInputSchemas(absoluteFilePath, route.method, route);\n\n    return {\n      method: route.method,\n      path: route.urlPath,\n      filePath: route.filePath,\n      isDynamic: route.isDynamic,\n      inputs,\n    };\n  });\n}\n\n/**\n * 提取一个路由文件的所有输入 schema\n *\n * 直接查询 schemaRegistry，复用参数校验已提取的 PropertyType，\n * 不再重复执行 AST 分析。\n */\nfunction extractInputSchemas(\n  filePath: string,\n  method: string,\n  route: { isDynamic: boolean; paramNames: string[] },\n): RouteInputSchema[] {\n  const inputs: RouteInputSchema[] = [];\n\n  // 主输入（query 或 body）：从 registry 查询\n  const inputType = getInputTypeForMethod(method);\n  const schema = getSchemaProperties(filePath, method, inputType);\n\n  if (schema) {\n    inputs.push({\n      source: inputType,\n      schemaName: schema.schemaName,\n      properties: schema.properties,\n    });\n  } else {\n    // registry 无数据（不应发生，插件 setup 时 registry 已加载）\n    inputs.push({\n      source: inputType,\n      schemaName: null,\n      properties: [],\n    });\n  }\n\n  // 动态路由参数\n  if (route.isDynamic && route.paramNames.length > 0) {\n    const paramsSchema = getSchemaProperties(filePath, method, 'params');\n\n    // params 有类型声明时用类型信息，否则用 paramNames 兜底\n    const paramsProps = (paramsSchema && paramsSchema.schemaName)\n      ? paramsSchema.properties\n      : route.paramNames.map((name) => ({\n          name,\n          type: 'string',\n          required: true,\n        }));\n\n    inputs.push({\n      source: 'params',\n      schemaName: paramsSchema?.schemaName ?? null,\n      properties: paramsProps,\n    });\n  }\n\n  return inputs;\n}\n"],"mappings":"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","names":["path"]}

package/package.json

@@ -0,0 +1,52 @@
+{
+  "name": "@faapi/schema",
+  "version": "0.0.0-canary.0",
+  "description": "Schema introspection for faapi — expose API schema to AI assistants via MCP",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "engines": {
+    "node": ">=22"
+  },
+  "scripts": {
+    "build": "tsup",
+    "prepublishOnly": "pnpm build",
+    "test": "vitest run --passWithNoTests",
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "@faapi/faapi": "workspace:*",
+    "@modelcontextprotocol/sdk": "^1.29.0",
+    "zod": "^4.4.3"
+  },
+  "devDependencies": {
+    "@types/node": "^22.15.0",
+    "@vitest/coverage-v8": "3",
+    "tsup": "^8.4.0",
+    "typescript": "^5.7.0",
+    "vitest": "^3.1.0"
+  },
+  "peerDependencies": {
+    "typescript": ">=5.7.0"
+  },
+  "peerDependenciesMeta": {
+    "typescript": {
+      "optional": true
+    }
+  },
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/faapi/faapi.git",
+    "directory": "packages/schema"
+  }
+}