mkdnsite 0.0.1 → 1.0.1

package/src/index.ts

@@ -13,6 +13,12 @@ export type { HandlerOptions } from './handler.ts'
 export { resolveConfig, DEFAULT_CONFIG } from './config/defaults.ts'
 export type {
   MkdnSiteConfig,
+  SiteConfig,
+  OgConfig,
+  AnalyticsConfig,
+  CspConfig,
+  CacheConfig,
+  FaviconConfig,
   ThemeConfig,
   NegotiationConfig,
   ClientConfig,
@@ -22,12 +28,30 @@ export type {
   LinkProps,
   ImageProps,
   CodeBlockProps,
-  InlineCodeProps
+  InlineCodeProps,
+  ColorTokens,
+  FontTokens,
+  LogoConfig
 } from './config/schema.ts'
 
+// Theme utilities
+export { buildThemeCss } from './theme/build-css.ts'
+export { BASE_THEME_CSS } from './theme/base-css.ts'
+
 // Content sources
 export { FilesystemSource } from './content/filesystem.ts'
 export { GitHubSource } from './content/github.ts'
+export { R2ContentSource } from './content/r2.ts'
+export type { R2ContentSourceConfig } from './content/r2.ts'
+export { AssetsSource } from './content/assets.ts'
+export type { AssetsSourceConfig } from './content/assets.ts'
+export { buildNavTree } from './content/nav-builder.ts'
+export type { ContentCache } from './content/cache.ts'
+export { MemoryContentCache, KVContentCache } from './content/cache.ts'
+export type { ResponseCache, CachedResponse } from './cache/response.ts'
+export { MemoryResponseCache } from './cache/memory.ts'
+export { KVResponseCache } from './cache/kv.ts'
+export type { FileEntry } from './content/nav-builder.ts'
 export type {
   ContentSource,
   ContentPage,
@@ -55,3 +79,27 @@ export { generateLlmsTxt } from './discovery/llmstxt.ts'
 export type { DeploymentAdapter } from './adapters/types.ts'
 export { detectRuntime } from './adapters/types.ts'
 export { LocalAdapter } from './adapters/local.ts'
+export { CloudflareAdapter } from './adapters/cloudflare.ts'
+export type { CloudflareEnv } from './adapters/cloudflare.ts'
+
+// Search
+export { createSearchIndex } from './search/index.ts'
+export type { SearchIndex, SearchResult, SerializedSearchIndex } from './search/index.ts'
+
+// MCP
+export { createMcpServer } from './mcp/server.ts'
+export { createMcpHandler } from './mcp/transport.ts'
+export type { McpConfig } from './config/schema.ts'
+
+// Traffic analytics
+export type {
+  TrafficAnalytics,
+  TrafficEvent,
+  TrafficType,
+  AnalyticsResponseFormat
+} from './analytics/types.ts'
+export { classifyTraffic, BOT_PATTERNS } from './analytics/classify.ts'
+export { NoopAnalytics } from './analytics/noop.ts'
+export { ConsoleAnalytics } from './analytics/console.ts'
+export { WorkersAnalyticsEngineAnalytics } from './adapters/cloudflare.ts'
+export type { TrafficAnalyticsConfig } from './config/schema.ts'

package/src/mcp/server.ts

@@ -0,0 +1,164 @@
+import { McpServer, ResourceTemplate } from '@modelcontextprotocol/sdk/server/mcp.js'
+import { z } from 'zod'
+import type { ContentSource } from '../content/types.ts'
+import type { SearchIndex } from '../search/index.ts'
+
+export function createMcpServer (opts: {
+  source: ContentSource
+  searchIndex: SearchIndex
+}): McpServer {
+  const { source, searchIndex } = opts
+
+  const server = new McpServer({
+    name: 'mkdnsite',
+    version: '0.1.0'
+  })
+
+  // ─── Tool: search_docs ──────────────────────────────────────────────────────
+
+  server.tool(
+    'search_docs',
+    'Full-text search across all documentation pages',
+    {
+      query: z.string().describe('Search query'),
+      limit: z.number().min(1).max(50).optional().describe('Max results (default 10, max 50)')
+    },
+    async ({ query, limit }) => {
+      const results = searchIndex.search(query, limit ?? 10)
+      return {
+        content: [{
+          type: 'text' as const,
+          text: JSON.stringify(results.map(r => ({
+            title: r.title,
+            slug: r.slug,
+            description: r.description,
+            excerpt: r.excerpt,
+            score: Math.round(r.score * 1000) / 1000
+          })), null, 2)
+        }]
+      }
+    }
+  )
+
+  // ─── Tool: get_page ─────────────────────────────────────────────────────────
+
+  server.tool(
+    'get_page',
+    'Retrieve the full markdown content of a documentation page by slug',
+    {
+      slug: z.string().describe('Page slug (e.g. /docs/getting-started)')
+    },
+    async ({ slug }) => {
+      const page = await source.getPage(slug)
+      if (page == null) {
+        return {
+          isError: true,
+          content: [{
+            type: 'text' as const,
+            text: `Page not found: ${slug}`
+          }]
+        }
+      }
+
+      const lines: string[] = []
+      if (page.meta.title != null) lines.push(`# ${String(page.meta.title)}`)
+      if (page.meta.description != null) lines.push(`> ${String(page.meta.description)}`)
+      if (lines.length > 0) lines.push('')
+      lines.push(page.body)
+
+      return {
+        content: [{
+          type: 'text' as const,
+          text: lines.join('\n')
+        }]
+      }
+    }
+  )
+
+  // ─── Tool: list_pages ───────────────────────────────────────────────────────
+
+  server.tool(
+    'list_pages',
+    'List all available documentation pages',
+    {},
+    async () => {
+      const pages = await source.listPages()
+      const list = pages.map(p => ({
+        title: String(p.meta.title ?? p.slug),
+        slug: p.slug,
+        description: p.meta.description != null ? String(p.meta.description) : undefined
+      }))
+      return {
+        content: [{
+          type: 'text' as const,
+          text: JSON.stringify(list, null, 2)
+        }]
+      }
+    }
+  )
+
+  // ─── Tool: get_nav ──────────────────────────────────────────────────────────
+
+  server.tool(
+    'get_nav',
+    'Get the documentation navigation tree',
+    {},
+    async () => {
+      const nav = await source.getNavTree()
+      return {
+        content: [{
+          type: 'text' as const,
+          text: JSON.stringify(nav, null, 2)
+        }]
+      }
+    }
+  )
+
+  // ─── Resources: pages ───────────────────────────────────────────────────────
+
+  const pageTemplate = new ResourceTemplate(
+    'mkdnsite://pages/{slug}',
+    {
+      list: async () => {
+        const pages = await source.listPages()
+        return {
+          resources: pages.map(p => ({
+            uri: `mkdnsite://pages${p.slug}`,
+            name: String(p.meta.title ?? p.slug),
+            description: p.meta.description != null ? String(p.meta.description) : undefined,
+            mimeType: 'text/markdown'
+          }))
+        }
+      }
+    }
+  )
+
+  server.resource(
+    'page',
+    pageTemplate,
+    { mimeType: 'text/markdown' },
+    async (uri) => {
+      // uri.href = "mkdnsite://pages/docs/getting-started"
+      const rawSlug = uri.href.replace(/^mkdnsite:\/\/pages/, '')
+      const resolvedSlug = rawSlug === '' ? '/' : rawSlug
+      const page = await source.getPage(resolvedSlug)
+      if (page == null) {
+        return { contents: [] }
+      }
+      const lines: string[] = []
+      if (page.meta.title != null) lines.push(`# ${String(page.meta.title)}`)
+      if (page.meta.description != null) lines.push(`> ${String(page.meta.description)}`)
+      if (lines.length > 0) lines.push('')
+      lines.push(page.body)
+      return {
+        contents: [{
+          uri: uri.href,
+          mimeType: 'text/markdown',
+          text: lines.join('\n')
+        }]
+      }
+    }
+  )
+
+  return server
+}

package/src/mcp/stdio.ts

@@ -0,0 +1,29 @@
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js'
+import type { MkdnSiteConfig } from '../config/schema.ts'
+import { createSearchIndex } from '../search/index.ts'
+import { createMcpServer } from './server.ts'
+
+/**
+ * Run the MCP server over stdio (JSON-RPC via stdin/stdout).
+ *
+ * Used by the `mkdnsite mcp` subcommand for MCP clients like Claude Desktop
+ * that communicate via stdio rather than HTTP. Does NOT start a web server.
+ */
+export async function runMcpStdio (config: MkdnSiteConfig): Promise<void> {
+  let source
+
+  if (config.github?.owner != null && config.github?.repo != null) {
+    const { GitHubSource } = await import('../content/github.ts')
+    source = new GitHubSource(config.github)
+  } else {
+    const { FilesystemSource } = await import('../content/filesystem.ts')
+    source = new FilesystemSource(config.contentDir)
+  }
+
+  const searchIndex = createSearchIndex()
+  await searchIndex.rebuild(source)
+
+  const server = createMcpServer({ source, searchIndex })
+  const transport = new StdioServerTransport()
+  await server.connect(transport)
+}

package/src/mcp/transport.ts

@@ -0,0 +1,29 @@
+import { WebStandardStreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/webStandardStreamableHttp.js'
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js'
+
+/**
+ * Creates a fetch-compatible handler that routes HTTP requests to the MCP server
+ * via the Web Standard Streamable HTTP transport.
+ *
+ * Uses stateless mode (no session management) — each request is independent.
+ * A single transport instance handles all concurrent requests.
+ */
+export function createMcpHandler (server: McpServer): (request: Request) => Promise<Response> {
+  const transport = new WebStandardStreamableHTTPServerTransport({
+    sessionIdGenerator: undefined // stateless mode
+  })
+
+  let connectPromise: Promise<void> | null = null
+
+  async function ensureConnected (): Promise<void> {
+    if (connectPromise == null) {
+      connectPromise = server.connect(transport)
+    }
+    await connectPromise
+  }
+
+  return async (request: Request): Promise<Response> => {
+    await ensureConnected()
+    return await transport.handleRequest(request)
+  }
+}

package/src/negotiate/headers.ts

@@ -1,13 +1,35 @@
-import type { ContentSignals } from '../config/schema.ts'
+import type { ContentSignals, CacheConfig } from '../config/schema.ts'
+
+function buildCacheControl (maxAge: number, swr: number): string {
+  let cc = 'public, max-age=' + String(maxAge)
+  if (swr > 0) cc += ', stale-while-revalidate=' + String(swr)
+  return cc
+}
+
+function buildEtag (versionTag: string, slug?: string): string {
+  // Sanitize versionTag: strip quotes and non-printable chars to prevent malformed ETag headers
+  // eslint-disable-next-line no-control-regex
+  const safeVersion = versionTag.replace(/["\\\x00-\x1f]/g, '')
+  const tag = slug != null ? safeVersion + '-' + slug.replace(/[^a-zA-Z0-9-]/g, '_') : safeVersion
+  return 'W/"' + tag + '"'
+}
 
 export function markdownHeaders (
   tokenCount: number | null,
-  signals?: ContentSignals
+  signals?: ContentSignals,
+  cache?: CacheConfig,
+  slug?: string
 ): Record<string, string> {
+  const maxAge = cache?.maxAgeMarkdown ?? 300
+  const swr = cache?.staleWhileRevalidate ?? 0
   const headers: Record<string, string> = {
     'Content-Type': 'text/markdown; charset=utf-8',
     Vary: 'Accept',
-    'Cache-Control': 'public, max-age=300'
+    'Cache-Control': buildCacheControl(maxAge, swr)
+  }
+
+  if (cache?.versionTag != null && cache.versionTag !== '') {
+    headers.ETag = buildEtag(cache.versionTag, slug)
   }
 
   if (tokenCount != null) {
@@ -16,9 +38,9 @@ export function markdownHeaders (
 
   if (signals != null) {
     const parts: string[] = []
-    if (signals.aiTrain !== undefined) parts.push(`ai-train=${signals.aiTrain}`)
-    if (signals.search !== undefined) parts.push(`search=${signals.search}`)
-    if (signals.aiInput !== undefined) parts.push(`ai-input=${signals.aiInput}`)
+    if (signals.aiTrain !== undefined) parts.push('ai-train=' + String(signals.aiTrain))
+    if (signals.search !== undefined) parts.push('search=' + String(signals.search))
+    if (signals.aiInput !== undefined) parts.push('ai-input=' + String(signals.aiInput))
     if (parts.length > 0) {
       headers['Content-Signal'] = parts.join(', ')
     }
@@ -27,12 +49,18 @@ export function markdownHeaders (
   return headers
 }
 
-export function htmlHeaders (): Record<string, string> {
-  return {
+export function htmlHeaders (cache?: CacheConfig, slug?: string): Record<string, string> {
+  const maxAge = cache?.maxAge ?? 300
+  const swr = cache?.staleWhileRevalidate ?? 0
+  const headers: Record<string, string> = {
     'Content-Type': 'text/html; charset=utf-8',
     Vary: 'Accept',
-    'Cache-Control': 'public, max-age=300'
+    'Cache-Control': buildCacheControl(maxAge, swr)
   }
+  if (cache?.versionTag != null && cache.versionTag !== '') {
+    headers.ETag = buildEtag(cache.versionTag, slug)
+  }
+  return headers
 }
 
 /**