apiskill 0.1.0

package/scripts/mcp-server.mjs

@@ -0,0 +1,408 @@
+#!/usr/bin/env node
+import {
+  checkCache,
+  crawlOpenApiUrl,
+  createApi,
+  createDocument,
+  deleteApi,
+  editApi,
+  formatSavedResult,
+  getAiContext,
+  getEndpointDetails,
+  getSchemaDetails,
+  importOpenApiCurl,
+  importOpenApiFile,
+  importOpenApiUrl,
+  listVersions,
+  queryApi,
+  searchEndpoints,
+} from './lib/apiskill-core.mjs';
+
+const SERVER_VERSION = '0.1.0';
+
+const tools = [
+  {
+    name: 'apiskill_check',
+    description: 'Check whether a usable cached OpenAPI document is configured. Returns import examples when no cache is available.',
+    inputSchema: {
+      type: 'object',
+      properties: {},
+    },
+  },
+  {
+    name: 'apiskill_help',
+    description: 'Show API Skill MCP help, including available tools, read/write categories, and import examples.',
+    inputSchema: {
+      type: 'object',
+      properties: {},
+    },
+  },
+  {
+    name: 'apiskill_list_versions',
+    description: 'List cached OpenAPI/Swagger document versions available to this API Skill MCP server.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        limit: { type: 'number', description: 'Maximum versions to return. Default 20.' },
+      },
+    },
+  },
+  {
+    name: 'apiskill_search_endpoints',
+    description: 'Search cached API endpoints by path, summary, tag, method, or parameter text.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        query: { type: 'string', description: 'Search keyword. Empty returns the first endpoints.' },
+        method: { type: 'string', description: 'Optional HTTP method filter such as GET or POST.' },
+        tag: { type: 'string', description: 'Optional tag filter.' },
+        versionId: { type: 'string', description: 'Optional cached version id. Defaults to latest.' },
+        limit: { type: 'number', description: 'Maximum results to return. Default 20.' },
+      },
+    },
+  },
+  {
+    name: 'apiskill_query_api',
+    description: 'CLI-equivalent endpoint query. A single match returns details or CLI config; multiple matches return candidates.',
+    inputSchema: {
+      type: 'object',
+      required: ['pathOrKeyword'],
+      properties: {
+        pathOrKeyword: { type: 'string', description: 'Exact API path or search keyword.' },
+        method: { type: 'string', description: 'Optional HTTP method filter such as GET or POST.' },
+        versionId: { type: 'string', description: 'Optional cached version id. Defaults to latest.' },
+        limit: { type: 'number', description: 'Maximum candidate rows when multiple endpoints match. Default 20.' },
+        format: { type: 'string', enum: ['json', 'cli', 'raw'], description: 'Single-match output format. Default json.' },
+      },
+    },
+  },
+  {
+    name: 'apiskill_get_endpoint',
+    description: 'Get one endpoint with request parameters, request body fields, response fields, manual config, and optional raw operation.',
+    inputSchema: {
+      type: 'object',
+      required: ['method', 'path'],
+      properties: {
+        method: { type: 'string', description: 'HTTP method, for example GET.' },
+        path: { type: 'string', description: 'Exact OpenAPI path.' },
+        versionId: { type: 'string', description: 'Optional cached version id. Defaults to latest.' },
+        includeRaw: { type: 'boolean', description: 'Whether to include raw OpenAPI operation JSON. Default false.' },
+      },
+    },
+  },
+  {
+    name: 'apiskill_get_ai_context',
+    description: 'Return AI-friendly Markdown for one endpoint, including parameters and response field descriptions.',
+    inputSchema: {
+      type: 'object',
+      required: ['method', 'path'],
+      properties: {
+        method: { type: 'string', description: 'HTTP method, for example POST.' },
+        path: { type: 'string', description: 'Exact OpenAPI path.' },
+        versionId: { type: 'string', description: 'Optional cached version id. Defaults to latest.' },
+      },
+    },
+  },
+  {
+    name: 'apiskill_get_schema',
+    description: 'Get a named schema from the cached OpenAPI document, with flattened field descriptions.',
+    inputSchema: {
+      type: 'object',
+      required: ['name'],
+      properties: {
+        name: { type: 'string', description: 'Schema name or suffix to resolve.' },
+        versionId: { type: 'string', description: 'Optional cached version id. Defaults to latest.' },
+      },
+    },
+  },
+  {
+    name: 'apiskill_import_url',
+    description: 'Import a direct OpenAPI/Swagger JSON or YAML URL into the local cache. This writes a new cached version.',
+    inputSchema: {
+      type: 'object',
+      required: ['url'],
+      properties: {
+        url: { type: 'string', description: 'Direct OpenAPI JSON/YAML URL.' },
+        auth: { type: 'string', description: 'Optional basic auth credentials in username:password format.' },
+      },
+    },
+  },
+  {
+    name: 'apiskill_crawl_openapi',
+    description: 'Crawl a Swagger UI / Knife4j / Redoc page and import the discovered OpenAPI document. This writes a new cached version.',
+    inputSchema: {
+      type: 'object',
+      required: ['url'],
+      properties: {
+        url: { type: 'string', description: 'Online API documentation page URL.' },
+        auth: { type: 'string', description: 'Optional basic auth credentials in username:password format.' },
+      },
+    },
+  },
+  {
+    name: 'apiskill_import_file',
+    description: 'Import a local OpenAPI/Swagger JSON or YAML file into the cache. This writes a new cached version.',
+    inputSchema: {
+      type: 'object',
+      required: ['file'],
+      properties: {
+        file: { type: 'string', description: 'Local JSON/YAML file path readable by the MCP server process.' },
+      },
+    },
+  },
+  {
+    name: 'apiskill_import_curl',
+    description: 'Execute a curl command or curl command file and import a JSON/YAML OpenAPI response. This writes a new cached version.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        curlText: { type: 'string', description: 'Curl command text.' },
+        curlFile: { type: 'string', description: 'Local file containing a curl command.' },
+      },
+    },
+  },
+  {
+    name: 'apiskill_create_document',
+    description: 'Create a blank local OpenAPI document version so agents can author API operations from scratch.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        title: { type: 'string', description: 'Document title. Default API Skill Document.' },
+        version: { type: 'string', description: 'OpenAPI info.version value. Default 1.0.0.' },
+        description: { type: 'string', description: 'Document description.' },
+        environmentName: { type: 'string', description: 'Optional environment name metadata.' },
+        environmentBaseUrl: { type: 'string', description: 'Optional environment base URL metadata.' },
+      },
+    },
+  },
+  {
+    name: 'apiskill_create_api',
+    description: 'Create a manual API operation. If versionId is omitted, this writes a new manual version.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        versionId: { type: 'string', description: 'Optional version id to append to. Defaults to a new manual version.' },
+        configText: { type: 'string', description: 'JSON/YAML/CLI config text. Use root key api, config, or operation.' },
+        config: { type: 'object', description: 'Manual API config object.' },
+      },
+    },
+  },
+  {
+    name: 'apiskill_edit_api',
+    description: 'Edit/replace one API operation in a cached version. Defaults to latest if versionId is omitted.',
+    inputSchema: {
+      type: 'object',
+      required: ['method', 'path'],
+      properties: {
+        method: { type: 'string', description: 'Original HTTP method.' },
+        path: { type: 'string', description: 'Original OpenAPI path.' },
+        versionId: { type: 'string', description: 'Optional version id. Defaults to latest.' },
+        configText: { type: 'string', description: 'Replacement JSON/YAML/CLI config text.' },
+        config: { type: 'object', description: 'Replacement manual API config object.' },
+      },
+    },
+  },
+  {
+    name: 'apiskill_delete_api',
+    description: 'Delete one API operation from a cached version. Defaults to latest if versionId is omitted.',
+    inputSchema: {
+      type: 'object',
+      required: ['method', 'path'],
+      properties: {
+        method: { type: 'string', description: 'HTTP method.' },
+        path: { type: 'string', description: 'OpenAPI path.' },
+        versionId: { type: 'string', description: 'Optional version id. Defaults to latest.' },
+      },
+    },
+  },
+];
+
+const handlers = {
+  apiskill_check: checkCache,
+  apiskill_help: async () => buildHelp(),
+  apiskill_list_versions: listVersions,
+  apiskill_search_endpoints: searchEndpoints,
+  apiskill_query_api: queryApi,
+  apiskill_get_endpoint: getEndpointDetails,
+  apiskill_get_ai_context: getAiContext,
+  apiskill_get_schema: getSchemaDetails,
+  apiskill_import_url: async (args) => formatSavedResult(await importOpenApiUrl(args)),
+  apiskill_crawl_openapi: async (args) => formatSavedResult(await crawlOpenApiUrl(args)),
+  apiskill_import_file: async (args) => formatSavedResult(await importOpenApiFile(args)),
+  apiskill_import_curl: async (args) => formatSavedResult(await importOpenApiCurl(args)),
+  apiskill_create_document: async (args) => formatSavedResult(await createDocument(args)),
+  apiskill_create_api: async (args) => formatSavedResult(await createApi(args)),
+  apiskill_edit_api: async (args) => formatSavedResult(await editApi(args)),
+  apiskill_delete_api: async (args) => formatSavedResult(await deleteApi(args)),
+};
+
+function buildHelp() {
+  const rootDir = process.env.APISKILL_ROOT || '/Users/dobby/dev/apiskill';
+  const cacheDir = process.env.APISKILL_CACHE_DIR || `${rootDir}/cache`;
+  const readTools = [
+    'apiskill_check',
+    'apiskill_help',
+    'apiskill_list_versions',
+    'apiskill_search_endpoints',
+    'apiskill_query_api',
+    'apiskill_get_endpoint',
+    'apiskill_get_ai_context',
+    'apiskill_get_schema',
+  ];
+  const writeTools = [
+    'apiskill_import_url',
+    'apiskill_crawl_openapi',
+    'apiskill_import_file',
+    'apiskill_import_curl',
+    'apiskill_create_document',
+    'apiskill_create_api',
+    'apiskill_edit_api',
+    'apiskill_delete_api',
+  ];
+  const byName = new Map(tools.map((tool) => [tool.name, tool]));
+  return {
+    name: 'API Skill MCP',
+    description: 'Search, import, and maintain cached OpenAPI/Swagger documents for coding tasks.',
+    startup: {
+      command: `node ${rootDir}/scripts/mcp-server.mjs`,
+      env: {
+        APISKILL_ROOT: rootDir,
+        APISKILL_CACHE_DIR: cacheDir,
+      },
+    },
+    quickStart: [
+      'Call apiskill_check first to verify that a usable cached OpenAPI document exists.',
+      'If no cache is available, import one with apiskill_import_url, apiskill_crawl_openapi, apiskill_import_file, or apiskill_import_curl, or create a blank one with apiskill_create_document.',
+      'Use apiskill_search_endpoints or apiskill_query_api to find endpoints.',
+      'Use apiskill_get_endpoint or apiskill_get_ai_context before implementing API integration code.',
+    ],
+    readTools: readTools.map((name) => ({ name, description: byName.get(name)?.description })),
+    writeTools: writeTools.map((name) => ({ name, description: byName.get(name)?.description })),
+    importExamples: {
+      apiskill_import_url: { url: 'https://example.com/openapi.json' },
+      apiskill_crawl_openapi: { url: 'https://example.com/swagger' },
+      apiskill_import_file: { file: '/absolute/path/openapi.yaml' },
+      apiskill_import_curl: { curlText: 'curl https://example.com/openapi.json' },
+      apiskill_create_document: { title: 'My API', version: '1.0.0' },
+    },
+    docs: {
+      english: `${rootDir}/docs/mcp.md`,
+      chinese: `${rootDir}/docs/mcp.zh.md`,
+    },
+  };
+}
+
+let inputBuffer = Buffer.alloc(0);
+
+process.stdin.on('data', (chunk) => {
+  inputBuffer = Buffer.concat([inputBuffer, chunk]);
+  parseMessages();
+});
+
+process.stdin.on('end', () => process.exit(0));
+
+function parseMessages() {
+  while (true) {
+    const headerEnd = inputBuffer.indexOf('\r\n\r\n');
+    if (headerEnd === -1) return;
+
+    const header = inputBuffer.slice(0, headerEnd).toString('utf8');
+    const match = /content-length:\s*(\d+)/i.exec(header);
+    if (!match) {
+      inputBuffer = inputBuffer.slice(headerEnd + 4);
+      continue;
+    }
+
+    const length = Number(match[1]);
+    const bodyStart = headerEnd + 4;
+    const bodyEnd = bodyStart + length;
+    if (inputBuffer.length < bodyEnd) return;
+
+    const raw = inputBuffer.slice(bodyStart, bodyEnd).toString('utf8');
+    inputBuffer = inputBuffer.slice(bodyEnd);
+    handleMessage(JSON.parse(raw)).catch((error) => {
+      if (raw.includes('"id"')) {
+        const id = safeParseId(raw);
+        sendError(id, -32603, error instanceof Error ? error.message : 'Internal error');
+      }
+    });
+  }
+}
+
+async function handleMessage(message) {
+  if (!Object.prototype.hasOwnProperty.call(message, 'id')) return;
+
+  if (message.method === 'initialize') {
+    sendResult(message.id, {
+      protocolVersion: message.params?.protocolVersion || '2024-11-05',
+      capabilities: { tools: {} },
+      serverInfo: { name: 'apiskill-mcp', version: SERVER_VERSION },
+    });
+    return;
+  }
+
+  if (message.method === 'ping') {
+    sendResult(message.id, {});
+    return;
+  }
+
+  if (message.method === 'tools/list') {
+    sendResult(message.id, { tools });
+    return;
+  }
+
+  if (message.method === 'tools/call') {
+    const toolName = message.params?.name;
+    const handler = handlers[toolName];
+    if (!handler) {
+      sendError(message.id, -32602, `Unknown tool: ${toolName}`);
+      return;
+    }
+
+    try {
+      const result = await handler(message.params?.arguments ?? {});
+      sendResult(message.id, {
+        content: [
+          {
+            type: 'text',
+            text: typeof result === 'string' ? result : JSON.stringify(result, null, 2),
+          },
+        ],
+      });
+    } catch (error) {
+      sendResult(message.id, {
+        isError: true,
+        content: [
+          {
+            type: 'text',
+            text: error instanceof Error ? error.message : 'Tool call failed',
+          },
+        ],
+      });
+    }
+    return;
+  }
+
+  sendError(message.id, -32601, `Unsupported method: ${message.method}`);
+}
+
+function sendResult(id, result) {
+  sendMessage({ jsonrpc: '2.0', id, result });
+}
+
+function sendError(id, code, message) {
+  sendMessage({ jsonrpc: '2.0', id, error: { code, message } });
+}
+
+function sendMessage(message) {
+  const body = JSON.stringify(message);
+  process.stdout.write(`Content-Length: ${Buffer.byteLength(body, 'utf8')}\r\n\r\n${body}`);
+}
+
+function safeParseId(raw) {
+  try {
+    return JSON.parse(raw).id ?? null;
+  } catch {
+    return null;
+  }
+}

package/skills/apiskill/SKILL.md

@@ -0,0 +1,71 @@
+---
+name: apiskill
+description: Search, import, and maintain cached Swagger/OpenAPI documents through the API Skill MCP server. Use when a user asks to find an API endpoint, inspect request parameters, request body fields, response fields, schema definitions, compare cached API versions, import API docs, maintain manual API configs, or gather source-of-truth API context before implementing frontend/backend integration code.
+---
+
+# API Skill
+
+## Overview
+
+Use API Skill to query and maintain locally cached Swagger/OpenAPI documents through MCP tools. Prefer it whenever API contract details matter, especially before coding a request, mapping response fields, or validating whether a field exists.
+
+## Workflow
+
+1. Start with `apiskill_check` when cache availability is unknown. If it reports no usable cache, ask whether to import/crawl through MCP, CLI, or the web app.
+2. Use `apiskill_help` when you need a compact MCP tool guide inside the client.
+3. Check available versions with `apiskill_list_versions` when version freshness matters or the user asks about a specific import.
+4. Search candidates with `apiskill_search_endpoints` or use CLI-equivalent `apiskill_query_api` when exact-match behavior or CLI config output is useful.
+5. Inspect the selected endpoint with `apiskill_get_endpoint` for structured parameters, request bodies, responses, manual config, and optionally raw OpenAPI operation JSON.
+6. Use `apiskill_get_ai_context` when the next step is coding or explaining an endpoint; it returns concise Markdown suitable for implementation notes.
+7. Use `apiskill_get_schema` when the user names a schema/model or when an endpoint response refers to a schema that needs field-level expansion.
+8. Only use import/create/edit/delete tools when the user explicitly wants to update the local API cache or maintain manual API operations.
+
+If the MCP tools are not visible in the current tool list, search for tools named `apiskill` and then call the matching MCP tool. If the server reports that no cached document exists, ask whether to import/crawl through MCP, CLI, or the API Skill web app.
+
+## Tool Guide
+
+`apiskill_check`
+: Check whether the current cache has a usable latest OpenAPI document. Use this before API work when cache state is unknown.
+
+`apiskill_help`
+: Show available MCP tools, read/write categories, import examples, and documentation paths.
+
+`apiskill_list_versions`
+: List cached OpenAPI/Swagger versions. Use this before answering questions about "latest", when comparing imports, or when a user provides a version id.
+
+`apiskill_search_endpoints`
+: Search endpoint path, summary, tag, method, and parameter text. Pass `method`, `tag`, `versionId`, and `limit` only when they help narrow results.
+
+`apiskill_query_api`
+: CLI-equivalent endpoint query. Use it when the user gives a path or keyword and expects either one exact API config or a candidate list. Set `format: "cli"` when the user wants CLI config text.
+
+`apiskill_get_endpoint`
+: Return structured endpoint details plus manual config. Set `includeRaw: true` only when raw OpenAPI metadata is needed for edge cases, vendor extensions, or exact source inspection.
+
+`apiskill_get_ai_context`
+: Return Markdown with request parameters, request body fields, and response fields. Use this output directly as the implementation contract when editing code.
+
+`apiskill_get_schema`
+: Resolve a schema by full name or suffix and return flattened fields plus raw schema. Use this for named models, DTOs, and response wrappers.
+
+`apiskill_import_url`, `apiskill_crawl_openapi`, `apiskill_import_file`, `apiskill_import_curl`
+: Import OpenAPI documents into the shared local cache. These tools write `cache/latest-import.json` and `cache/versions/`.
+
+`apiskill_create_api`, `apiskill_edit_api`, `apiskill_delete_api`
+: Maintain manual API operations in cached versions. These are write tools; use them only when the user asks to modify local API docs.
+
+## Usage Rules
+
+- Treat cached OpenAPI data as the API contract source, but mention the selected `versionId` when the answer depends on a specific cached import.
+- When multiple endpoints match, prefer exact path and method matches first, then use summaries/tags to disambiguate.
+- Do not infer field names from nearby endpoints when the requested endpoint or schema can be queried directly.
+- For implementation tasks, quote the method, path, required request fields, and response fields that drive the code change.
+- Do not call write tools just to answer a read-only API question.
+- Keep answers scoped to the API data returned by the tools unless the user asks for broader analysis.
+
+## Common Prompts
+
+- "搜索会员列表相关接口。"
+- "查一下 `POST /api/v1/member/create` 的请求体和响应字段。"
+- "这个字段应该从哪个响应字段取？先查接口文档。"
+- "把 `UserSearchRes` schema 展开成前端字段说明。"

package/skills/apiskill/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "API Skill"
+  short_description: "Search cached OpenAPI docs"
+  default_prompt: "Use $apiskill to search cached Swagger/OpenAPI endpoints and schemas before coding against an API."