doccupine 0.0.85 → 0.0.86

package/dist/templates/services/llm/config.d.ts

@@ -1 +1 @@
-export declare const llmConfigTemplate = "import type {\n  LLMConfig,\n  LLMProvider,\n  ProviderDefaults,\n} from \"@/services/llm/types\";\nconst PROVIDER_DEFAULTS: ProviderDefaults = {\n  openai: {\n    chat: \"gpt-4.1-nano\",\n    embedding: \"text-embedding-3-small\",\n  },\n  anthropic: {\n    chat: \"claude-sonnet-4-5-20250929\",\n    embedding: \"text-embedding-3-small\", // Fallback to OpenAI\n  },\n  google: {\n    chat: \"gemini-2.5-flash-lite\",\n    embedding: \"gemini-embedding-001\",\n  },\n};\nfunction validateAPIKeys(provider: LLMProvider): void {\n  const requiredKeys: Record<LLMProvider, string> = {\n    openai: \"OPENAI_API_KEY\",\n    anthropic: \"ANTHROPIC_API_KEY\",\n    google: \"GOOGLE_API_KEY\",\n  };\n  const keyName = requiredKeys[provider];\n  const keyValue = process.env[keyName];\n  if (!keyValue) {\n    throw new Error(\n      `Missing API key for ${provider}. Please set ${keyName} in your environment variables.`,\n    );\n  }\n  if (provider === \"anthropic\" && !process.env.OPENAI_API_KEY) {\n    throw new Error(\n      \"Anthropic provider requires OPENAI_API_KEY for embeddings. Please set OPENAI_API_KEY in your environment variables.\",\n    );\n  }\n}\nexport function getLLMConfig(): LLMConfig {\n  const provider = (process.env.LLM_PROVIDER || \"openai\") as LLMProvider;\n  if (![\"openai\", \"anthropic\", \"google\"].includes(provider)) {\n    throw new Error(\n      `Invalid LLM_PROVIDER: ${provider}. Must be one of: openai, anthropic, google`,\n    );\n  }\n  validateAPIKeys(provider);\n  const defaults = PROVIDER_DEFAULTS[provider];\n  return {\n    provider,\n    chatModel: process.env.LLM_CHAT_MODEL || defaults.chat,\n    embeddingModel: process.env.LLM_EMBEDDING_MODEL || defaults.embedding,\n    temperature: parseFloat(process.env.LLM_TEMPERATURE || \"0\"),\n  };\n}\n";
+export declare const llmConfigTemplate = "import type {\n  LLMConfig,\n  LLMProvider,\n  ProviderDefaults,\n} from \"@/services/llm/types\";\nconst PROVIDER_DEFAULTS: ProviderDefaults = {\n  openai: {\n    chat: \"gpt-4.1-nano\",\n    embedding: \"text-embedding-3-small\",\n  },\n  anthropic: {\n    chat: \"claude-sonnet-4-5-20250929\",\n    embedding: \"text-embedding-3-small\", // Fallback to OpenAI\n  },\n  google: {\n    chat: \"gemini-2.5-flash-lite\",\n    embedding: \"gemini-embedding-001\",\n  },\n};\nfunction validateAPIKeys(provider: LLMProvider): void {\n  const requiredKeys: Record<LLMProvider, string> = {\n    openai: \"OPENAI_API_KEY\",\n    anthropic: \"ANTHROPIC_API_KEY\",\n    google: \"GOOGLE_API_KEY\",\n  };\n  const keyName = requiredKeys[provider];\n  const keyValue = process.env[keyName];\n  if (!keyValue) {\n    throw new Error(\n      `Missing API key for ${provider}. Please set ${keyName} in your environment variables.`,\n    );\n  }\n  if (provider === \"anthropic\" && !process.env.OPENAI_API_KEY) {\n    throw new Error(\n      \"Anthropic provider requires OPENAI_API_KEY for embeddings. Please set OPENAI_API_KEY in your environment variables.\",\n    );\n  }\n}\nexport function isLLMAvailable(): boolean {\n  const provider = (process.env.LLM_PROVIDER || \"openai\") as LLMProvider;\n  const requiredKeys: Record<LLMProvider, string> = {\n    openai: \"OPENAI_API_KEY\",\n    anthropic: \"ANTHROPIC_API_KEY\",\n    google: \"GOOGLE_API_KEY\",\n  };\n  const keyName = requiredKeys[provider];\n  if (!keyName || !process.env[keyName]) return false;\n  if (provider === \"anthropic\" && !process.env.OPENAI_API_KEY) return false;\n  return true;\n}\nexport function getLLMConfig(): LLMConfig {\n  const provider = (process.env.LLM_PROVIDER || \"openai\") as LLMProvider;\n  if (![\"openai\", \"anthropic\", \"google\"].includes(provider)) {\n    throw new Error(\n      `Invalid LLM_PROVIDER: ${provider}. Must be one of: openai, anthropic, google`,\n    );\n  }\n  validateAPIKeys(provider);\n  const defaults = PROVIDER_DEFAULTS[provider];\n  return {\n    provider,\n    chatModel: process.env.LLM_CHAT_MODEL || defaults.chat,\n    embeddingModel: process.env.LLM_EMBEDDING_MODEL || defaults.embedding,\n    temperature: parseFloat(process.env.LLM_TEMPERATURE || \"0\"),\n  };\n}\n";

package/dist/templates/services/llm/config.js

@@ -36,6 +36,18 @@ function validateAPIKeys(provider: LLMProvider): void {
     );
   }
 }
+export function isLLMAvailable(): boolean {
+  const provider = (process.env.LLM_PROVIDER || "openai") as LLMProvider;
+  const requiredKeys: Record<LLMProvider, string> = {
+    openai: "OPENAI_API_KEY",
+    anthropic: "ANTHROPIC_API_KEY",
+    google: "GOOGLE_API_KEY",
+  };
+  const keyName = requiredKeys[provider];
+  if (!keyName || !process.env[keyName]) return false;
+  if (provider === "anthropic" && !process.env.OPENAI_API_KEY) return false;
+  return true;
+}
 export function getLLMConfig(): LLMConfig {
   const provider = (process.env.LLM_PROVIDER || "openai") as LLMProvider;
   if (!["openai", "anthropic", "google"].includes(provider)) {

package/dist/templates/services/mcp/server.d.ts

@@ -1 +1 @@
-export declare const mcpServerTemplate = "import { McpServer } from \"@modelcontextprotocol/sdk/server/mcp.js\";\nimport { z } from \"zod\";\nimport {\n  listDocs,\n  getDoc,\n  getAllDocsChunks,\n  DOCS_TOOLS,\n} from \"@/services/mcp/tools\";\nimport { getLLMConfig, createEmbeddings } from \"@/services/llm\";\nimport type { DocsChunk } from \"@/services/mcp/types\";\n\n/**\n * In-memory cache for document embeddings.\n * Built once at server startup since docs are static.\n */\nlet docsIndex: {\n  ready: boolean;\n  building: boolean;\n  chunks: (DocsChunk & { embedding: number[] })[];\n} = {\n  ready: false,\n  building: false,\n  chunks: [],\n};\n\n/** Resolves when the initial index build completes */\nlet indexReady: Promise<void> | null = null;\n\n/**\n * Cosine similarity between two vectors\n */\nfunction cosineSim(a: number[], b: number[]): number {\n  let dot = 0,\n    na = 0,\n    nb = 0;\n  for (let i = 0; i < a.length; i++) {\n    const x = a[i];\n    const y = b[i];\n    dot += x * y;\n    na += x * x;\n    nb += y * y;\n  }\n  if (na === 0 || nb === 0) return 0;\n  return dot / (Math.sqrt(na) * Math.sqrt(nb));\n}\n\n/**\n * Build or rebuild the documentation index\n */\nasync function buildDocsIndex(force = false): Promise<void> {\n  if (docsIndex.building) return;\n  if (docsIndex.ready && !force) return;\n\n  docsIndex.building = true;\n  try {\n    const chunks = await getAllDocsChunks();\n\n    if (chunks.length === 0) {\n      docsIndex.chunks = [];\n      docsIndex.ready = true;\n      return;\n    }\n\n    const config = getLLMConfig();\n    const embeddings = createEmbeddings(config);\n\n    // Process embeddings in small batches to avoid exceeding token limits\n    const BATCH_SIZE = 10;\n    const texts = chunks.map((c) => c.text);\n    const vectors: number[][] = [];\n\n    for (let i = 0; i < texts.length; i += BATCH_SIZE) {\n      const batch = texts.slice(i, i + BATCH_SIZE);\n      const batchVectors = await embeddings.embedDocuments(batch);\n      vectors.push(...batchVectors);\n    }\n\n    docsIndex.chunks = chunks.map((c, i) => ({\n      ...c,\n      embedding: vectors[i],\n    }));\n    docsIndex.ready = true;\n  } catch (error) {\n    // Reset so the next call to ensureDocsIndex retries\n    indexReady = null;\n    throw error;\n  } finally {\n    docsIndex.building = false;\n  }\n}\n\n/**\n * Ensure the docs index is ready.\n * On first call, triggers the build; subsequent calls wait for the same promise.\n */\nexport async function ensureDocsIndex(force = false): Promise<void> {\n  if (force) {\n    // Wait for any in-flight build before starting a forced rebuild\n    if (docsIndex.building && indexReady) {\n      await indexReady.catch(() => {});\n    }\n    docsIndex.ready = false;\n    docsIndex.chunks = [];\n    indexReady = buildDocsIndex(true);\n    return indexReady;\n  }\n  if (!indexReady) {\n    indexReady = buildDocsIndex();\n  }\n  return indexReady;\n}\n\n// Eagerly start building the index on server startup (docs are static)\nindexReady = buildDocsIndex();\n\n/** Cached embeddings instance for search queries */\nlet cachedEmbeddings: ReturnType<typeof createEmbeddings> | null = null;\n\nfunction getEmbeddings() {\n  if (!cachedEmbeddings) {\n    cachedEmbeddings = createEmbeddings(getLLMConfig());\n  }\n  return cachedEmbeddings;\n}\n\n/**\n * Search documents using semantic similarity\n */\nexport async function searchDocs(\n  query: string,\n  limit = 6,\n): Promise<{ chunk: DocsChunk; score: number }[]> {\n  await ensureDocsIndex();\n\n  const queryVector = await getEmbeddings().embedQuery(query);\n\n  const scored = docsIndex.chunks\n    .map((c) => ({\n      chunk: { id: c.id, text: c.text, path: c.path, uri: c.uri },\n      score: cosineSim(queryVector, c.embedding),\n    }))\n    .sort((a, b) => b.score - a.score)\n    .slice(0, limit);\n\n  return scored;\n}\n\n/**\n * Get the current index status\n */\nexport function getIndexStatus(): { ready: boolean; chunkCount: number } {\n  return {\n    ready: docsIndex.ready,\n    chunkCount: docsIndex.chunks.length,\n  };\n}\n\n/**\n * Create and configure the MCP server with documentation tools\n */\nexport function createMCPServer(): McpServer {\n  const server = new McpServer({\n    name: \"docs-server\",\n    version: \"1.0.0\",\n  });\n\n  // Register the search_docs tool\n  server.tool(\n    \"search_docs\",\n    DOCS_TOOLS[0].description,\n    {\n      query: z\n        .string()\n        .describe(\"The search query to find relevant documentation\"),\n      limit: z\n        .number()\n        .optional()\n        .describe(\"Maximum number of results to return (default: 6)\"),\n    },\n    async ({ query, limit }) => {\n      const results = await searchDocs(query, limit ?? 6);\n      return {\n        content: [\n          {\n            type: \"text\" as const,\n            text: JSON.stringify(\n              results.map(({ chunk, score }) => ({\n                path: chunk.path,\n                uri: chunk.uri,\n                score: score.toFixed(3),\n                text: chunk.text,\n              })),\n              null,\n              2,\n            ),\n          },\n        ],\n      };\n    },\n  );\n\n  // Register the get_doc tool\n  server.tool(\n    \"get_doc\",\n    DOCS_TOOLS[1].description,\n    {\n      path: z.string().describe(\"The file path to the documentation page\"),\n    },\n    async ({ path }) => {\n      const doc = await getDoc({ path });\n      if (!doc) {\n        return {\n          content: [\n            {\n              type: \"text\" as const,\n              text: JSON.stringify({ error: \"Document not found\" }),\n            },\n          ],\n          isError: true,\n        };\n      }\n      return {\n        content: [\n          {\n            type: \"text\" as const,\n            text: JSON.stringify(doc, null, 2),\n          },\n        ],\n      };\n    },\n  );\n\n  // Register the list_docs tool\n  server.tool(\n    \"list_docs\",\n    DOCS_TOOLS[2].description,\n    {\n      directory: z\n        .string()\n        .optional()\n        .describe(\"Optional directory to filter results\"),\n    },\n    async ({ directory }) => {\n      const docs = await listDocs({ directory });\n      return {\n        content: [\n          {\n            type: \"text\" as const,\n            text: JSON.stringify(\n              docs.map((d) => ({\n                name: d.name,\n                path: d.path,\n                uri: d.uri,\n              })),\n              null,\n              2,\n            ),\n          },\n        ],\n      };\n    },\n  );\n\n  // Register documentation as resources\n  server.resource(\"docs://list\", \"docs://list\", async () => {\n    const docs = await listDocs();\n    return {\n      contents: [\n        {\n          uri: \"docs://list\",\n          text: JSON.stringify(\n            docs.map((d) => ({ name: d.name, path: d.path, uri: d.uri })),\n            null,\n            2,\n          ),\n        },\n      ],\n    };\n  });\n\n  return server;\n}\n";
+export declare const mcpServerTemplate = "import { McpServer } from \"@modelcontextprotocol/sdk/server/mcp.js\";\nimport { z } from \"zod\";\nimport {\n  listDocs,\n  getDoc,\n  getAllDocsChunks,\n  DOCS_TOOLS,\n} from \"@/services/mcp/tools\";\nimport { getLLMConfig, isLLMAvailable, createEmbeddings } from \"@/services/llm\";\nimport type { DocsChunk } from \"@/services/mcp/types\";\n\n/**\n * In-memory cache for document embeddings.\n * Built once at server startup since docs are static.\n */\nlet docsIndex: {\n  ready: boolean;\n  building: boolean;\n  chunks: (DocsChunk & { embedding: number[] })[];\n} = {\n  ready: false,\n  building: false,\n  chunks: [],\n};\n\n/** Resolves when the initial index build completes */\nlet indexReady: Promise<void> | null = null;\n\n/**\n * Cosine similarity between two vectors\n */\nfunction cosineSim(a: number[], b: number[]): number {\n  let dot = 0,\n    na = 0,\n    nb = 0;\n  for (let i = 0; i < a.length; i++) {\n    const x = a[i];\n    const y = b[i];\n    dot += x * y;\n    na += x * x;\n    nb += y * y;\n  }\n  if (na === 0 || nb === 0) return 0;\n  return dot / (Math.sqrt(na) * Math.sqrt(nb));\n}\n\n/**\n * Build or rebuild the documentation index\n */\nasync function buildDocsIndex(force = false): Promise<void> {\n  if (docsIndex.building) return;\n  if (docsIndex.ready && !force) return;\n\n  docsIndex.building = true;\n  try {\n    const chunks = await getAllDocsChunks();\n\n    if (chunks.length === 0) {\n      docsIndex.chunks = [];\n      docsIndex.ready = true;\n      return;\n    }\n\n    const config = getLLMConfig();\n    const embeddings = createEmbeddings(config);\n\n    // Process embeddings in small batches to avoid exceeding token limits\n    const BATCH_SIZE = 10;\n    const texts = chunks.map((c) => c.text);\n    const vectors: number[][] = [];\n\n    for (let i = 0; i < texts.length; i += BATCH_SIZE) {\n      const batch = texts.slice(i, i + BATCH_SIZE);\n      const batchVectors = await embeddings.embedDocuments(batch);\n      vectors.push(...batchVectors);\n    }\n\n    docsIndex.chunks = chunks.map((c, i) => ({\n      ...c,\n      embedding: vectors[i],\n    }));\n    docsIndex.ready = true;\n  } catch (error) {\n    // Reset so the next call to ensureDocsIndex retries\n    indexReady = null;\n    throw error;\n  } finally {\n    docsIndex.building = false;\n  }\n}\n\n/**\n * Ensure the docs index is ready.\n * On first call, triggers the build; subsequent calls wait for the same promise.\n */\nexport async function ensureDocsIndex(force = false): Promise<void> {\n  if (force) {\n    // Wait for any in-flight build before starting a forced rebuild\n    if (docsIndex.building && indexReady) {\n      await indexReady.catch(() => {});\n    }\n    docsIndex.ready = false;\n    docsIndex.chunks = [];\n    indexReady = buildDocsIndex(true);\n    return indexReady;\n  }\n  if (!indexReady) {\n    indexReady = buildDocsIndex();\n  }\n  return indexReady;\n}\n\n// Eagerly start building the index on server startup if LLM is configured\nif (isLLMAvailable()) {\n  indexReady = buildDocsIndex();\n}\n\n/** Cached embeddings instance for search queries */\nlet cachedEmbeddings: ReturnType<typeof createEmbeddings> | null = null;\n\nfunction getEmbeddings() {\n  if (!cachedEmbeddings) {\n    cachedEmbeddings = createEmbeddings(getLLMConfig());\n  }\n  return cachedEmbeddings;\n}\n\n/**\n * Search documents using semantic similarity\n */\nexport async function searchDocs(\n  query: string,\n  limit = 6,\n): Promise<{ chunk: DocsChunk; score: number }[]> {\n  await ensureDocsIndex();\n\n  const queryVector = await getEmbeddings().embedQuery(query);\n\n  const scored = docsIndex.chunks\n    .map((c) => ({\n      chunk: { id: c.id, text: c.text, path: c.path, uri: c.uri },\n      score: cosineSim(queryVector, c.embedding),\n    }))\n    .sort((a, b) => b.score - a.score)\n    .slice(0, limit);\n\n  return scored;\n}\n\n/**\n * Get the current index status\n */\nexport function getIndexStatus(): { ready: boolean; chunkCount: number } {\n  return {\n    ready: docsIndex.ready,\n    chunkCount: docsIndex.chunks.length,\n  };\n}\n\n/**\n * Create and configure the MCP server with documentation tools\n */\nexport function createMCPServer(): McpServer {\n  const server = new McpServer({\n    name: \"docs-server\",\n    version: \"1.0.0\",\n  });\n\n  // Register the search_docs tool\n  server.tool(\n    \"search_docs\",\n    DOCS_TOOLS[0].description,\n    {\n      query: z\n        .string()\n        .describe(\"The search query to find relevant documentation\"),\n      limit: z\n        .number()\n        .optional()\n        .describe(\"Maximum number of results to return (default: 6)\"),\n    },\n    async ({ query, limit }) => {\n      const results = await searchDocs(query, limit ?? 6);\n      return {\n        content: [\n          {\n            type: \"text\" as const,\n            text: JSON.stringify(\n              results.map(({ chunk, score }) => ({\n                path: chunk.path,\n                uri: chunk.uri,\n                score: score.toFixed(3),\n                text: chunk.text,\n              })),\n              null,\n              2,\n            ),\n          },\n        ],\n      };\n    },\n  );\n\n  // Register the get_doc tool\n  server.tool(\n    \"get_doc\",\n    DOCS_TOOLS[1].description,\n    {\n      path: z.string().describe(\"The file path to the documentation page\"),\n    },\n    async ({ path }) => {\n      const doc = await getDoc({ path });\n      if (!doc) {\n        return {\n          content: [\n            {\n              type: \"text\" as const,\n              text: JSON.stringify({ error: \"Document not found\" }),\n            },\n          ],\n          isError: true,\n        };\n      }\n      return {\n        content: [\n          {\n            type: \"text\" as const,\n            text: JSON.stringify(doc, null, 2),\n          },\n        ],\n      };\n    },\n  );\n\n  // Register the list_docs tool\n  server.tool(\n    \"list_docs\",\n    DOCS_TOOLS[2].description,\n    {\n      directory: z\n        .string()\n        .optional()\n        .describe(\"Optional directory to filter results\"),\n    },\n    async ({ directory }) => {\n      const docs = await listDocs({ directory });\n      return {\n        content: [\n          {\n            type: \"text\" as const,\n            text: JSON.stringify(\n              docs.map((d) => ({\n                name: d.name,\n                path: d.path,\n                uri: d.uri,\n              })),\n              null,\n              2,\n            ),\n          },\n        ],\n      };\n    },\n  );\n\n  // Register documentation as resources\n  server.resource(\"docs://list\", \"docs://list\", async () => {\n    const docs = await listDocs();\n    return {\n      contents: [\n        {\n          uri: \"docs://list\",\n          text: JSON.stringify(\n            docs.map((d) => ({ name: d.name, path: d.path, uri: d.uri })),\n            null,\n            2,\n          ),\n        },\n      ],\n    };\n  });\n\n  return server;\n}\n";

package/dist/templates/services/mcp/server.js

@@ -6,7 +6,7 @@ import {
   getAllDocsChunks,
   DOCS_TOOLS,
 } from "@/services/mcp/tools";
-import { getLLMConfig, createEmbeddings } from "@/services/llm";
+import { getLLMConfig, isLLMAvailable, createEmbeddings } from "@/services/llm";
 import type { DocsChunk } from "@/services/mcp/types";
 
 /**
@@ -110,8 +110,10 @@ export async function ensureDocsIndex(force = false): Promise<void> {
   return indexReady;
 }
 
-// Eagerly start building the index on server startup (docs are static)
-indexReady = buildDocsIndex();
+// Eagerly start building the index on server startup if LLM is configured
+if (isLLMAvailable()) {
+  indexReady = buildDocsIndex();
+}
 
 /** Cached embeddings instance for search queries */
 let cachedEmbeddings: ReturnType<typeof createEmbeddings> | null = null;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "doccupine",
-  "version": "0.0.85",
+  "version": "0.0.86",
   "description": "Free and open-source documentation platform. Write MDX, get a production-ready site with AI chat, built-in components, and an MCP server - in one command.",
   "main": "dist/index.js",
   "bin": {