contentbase 0.1.8 → 0.4.0

package/src/mcp/prompts.ts

@@ -0,0 +1,199 @@
+import { z } from 'zod'
+import path from 'node:path'
+import fs from 'node:fs/promises'
+import { introspectMetaSchema, validateDocument } from '../index.js'
+
+export function registerPrompts(mcpServer: any, collection: any) {
+  const modelDefs = collection.modelDefinitions as any[]
+
+  // Per-model creation prompts
+  for (const def of modelDefs) {
+    const modelName = (def as any).name as string
+    const promptName = `create-${modelName.toLowerCase()}`
+
+    mcpServer.prompt(promptName, {
+      description: `Guide creation of a new ${modelName} document with proper schema and sections`,
+      args: {
+        title: z.string().describe('Title for the new document'),
+      },
+      handler: (args: { title?: string }) => {
+        const fields = introspectMetaSchema((def as any).meta)
+        const sections = Object.entries((def as any).sections || {}).map(([key, sec]: [string, any]) => ({
+          key,
+          heading: sec.heading,
+          hasSchema: !!sec.schema,
+        }))
+
+        const fieldDocs = fields.map((f: any) =>
+          `- **${f.name}** (${f.type}${f.required ? ', required' : ''})${f.description ? `: ${f.description}` : ''}${f.defaultValue !== undefined ? ` [default: ${JSON.stringify(f.defaultValue)}]` : ''}`,
+        ).join('\n')
+
+        const sectionDocs = sections.map((s: any) =>
+          `- **${s.heading}** (key: \`${s.key}\`)${s.hasSchema ? ' — has schema validation' : ''}`,
+        ).join('\n')
+
+        const content = [
+          `# Create a new ${modelName}`,
+          '',
+          `Title: ${args.title || '(not specified)'}`,
+          '',
+          '## Frontmatter Fields',
+          '',
+          fieldDocs || '(no schema fields defined)',
+          '',
+          '## Sections',
+          '',
+          sectionDocs || '(no sections defined)',
+          '',
+          '## Instructions',
+          '',
+          `Use the \`create_document\` tool with model="${modelName}" and fill in the meta fields.`,
+          'Then use `update_section` to populate each section with content.',
+        ].join('\n')
+
+        return [{ role: 'user' as const, content }]
+      },
+    })
+  }
+
+  mcpServer.prompt('review-document', {
+    description: 'Fetch a document, run validation, and present it for review',
+    args: {
+      pathId: z.string().describe('Document path ID to review'),
+    },
+    handler: (args: { pathId?: string }) => {
+      const pathId = args.pathId
+      if (!pathId) {
+        return [{ role: 'user' as const, content: 'Error: pathId argument is required.' }]
+      }
+
+      const doc = collection.document(pathId)
+      if (!doc) {
+        return [{ role: 'user' as const, content: `Document not found: ${pathId}` }]
+      }
+
+      const def = collection.findModelDefinition(pathId)
+      let validationText = ''
+      if (def) {
+        const result = validateDocument(doc, def)
+        validationText = result.valid
+          ? '\n**Validation: PASSED**\n'
+          : `\n**Validation: FAILED**\n\nErrors:\n${result.errors.map((e: any) => `- ${e.path.join('.')}: ${e.message}`).join('\n')}\n`
+      } else {
+        validationText = '\n*No model definition found — validation skipped.*\n'
+      }
+
+      const content = [
+        `# Review: ${doc.title}`,
+        '',
+        `**Path:** ${pathId}`,
+        `**Model:** ${def ? (def as any).name : 'untyped'}`,
+        validationText,
+        '## Outline',
+        '',
+        doc.toOutline(),
+        '',
+        '## Frontmatter',
+        '',
+        '```json',
+        JSON.stringify(doc.meta, null, 2),
+        '```',
+        '',
+        '## Content',
+        '',
+        doc.content,
+      ].join('\n')
+
+      return [{ role: 'user' as const, content }]
+    },
+  })
+
+  mcpServer.prompt('teach', {
+    description: 'Full contentbase documentation — models, table of contents, CLI reference, and API primer. For a quick-start behavioral guide, use the `read_me` tool instead.',
+    handler: async () => {
+      const modelsSummary = collection.generateModelSummary()
+      const toc = collection.tableOfContents({ title: 'Table of Contents' })
+
+      const packageRoot = path.resolve(import.meta.dir, '../..')
+      let primer = ''
+      let cli = ''
+      try {
+        primer = await fs.readFile(path.join(packageRoot, 'PRIMER.md'), 'utf8')
+      } catch {}
+      try {
+        cli = await fs.readFile(path.join(packageRoot, 'CLI.md'), 'utf8')
+      } catch {}
+
+      const content = [
+        '> **Quick start:** Call the `read_me` tool for a concise behavioral guide. This prompt provides the full reference.',
+        '',
+        modelsSummary.trimEnd(),
+        '', '---', '',
+        toc.trimEnd(),
+        '', '---', '',
+        cli.trimEnd(),
+        '', '---', '',
+        primer.trimEnd(),
+      ].join('\n')
+
+      return [{ role: 'user' as const, content }]
+    },
+  })
+
+  mcpServer.prompt('query-guide', {
+    description: 'Show available models, fields, and query operators to help build queries',
+    args: {
+      intent: z.string().optional().describe('What you want to find (helps tailor the guide)'),
+    },
+    handler: () => {
+      const modelsInfo = modelDefs.map((def: any) => {
+        const fields = introspectMetaSchema(def.meta)
+        const fieldList = fields.map((f: any) => `  - ${f.name} (${f.type})`).join('\n')
+        return `### ${def.name} (prefix: ${def.prefix})\n${fieldList || '  (no schema fields)'}`
+      }).join('\n\n')
+
+      const content = [
+        '# Query Guide',
+        '',
+        '## Available Models',
+        '',
+        modelsInfo || '(no models registered)',
+        '',
+        '## Query Operators',
+        '',
+        '| Operator | Description | Example value |',
+        '|----------|-------------|---------------|',
+        '| eq | Exact equality (default) | `"published"` |',
+        '| in | Value is in array | `["draft", "published"]` |',
+        '| notIn | Value is not in array | `["archived"]` |',
+        '| gt / lt / gte / lte | Numeric/date comparison | `5` |',
+        '| contains | String contains substring | `"auth"` |',
+        '| startsWith / endsWith | String prefix/suffix | `"user-"` |',
+        '| regex | Regex pattern match | `"^v\\\\d+"` |',
+        '| exists / notExists | Field presence check | (no value needed) |',
+        '',
+        '## Example (MongoDB-style DSL)',
+        '',
+        '```json',
+        '{',
+        '  "model": "Epic",',
+        '  "where": {',
+        '    "meta.status": "active",',
+        '    "meta.priority": { "$in": ["high", "critical"] }',
+        '  },',
+        '  "sort": { "meta.priority": "desc" },',
+        '  "limit": 10',
+        '}',
+        '```',
+        '',
+        'Where value shortcuts:',
+        '- Literal value → implicit $eq: `"meta.status": "active"`',
+        '- Array → implicit $in: `"meta.tags": ["a", "b"]`',
+        '- Operator object: `"meta.priority": { "$gt": 5 }`',
+        '- Multiple operators: `"meta.priority": { "$gte": 3, "$lte": 8 }`',
+      ].join('\n')
+
+      return [{ role: 'user' as const, content }]
+    },
+  })
+}

package/src/mcp/readme.ts

@@ -0,0 +1,153 @@
+import { introspectMetaSchema } from '../index.js'
+
+export function generateReadMe(collection: any, modelDefs: any[]) {
+  const lines: string[] = []
+
+  // Section 1: The Rules
+  const rootPath = collection.rootPath as string
+
+  lines.push(
+    '# Contentbase Collection Guide',
+    '',
+    `> **This collection is located at \`${rootPath}\`.**`,
+    '',
+    '## Rules — READ CAREFULLY',
+    '',
+    `**Every markdown file under \`${rootPath}\` is a structured document governed by a model schema.** These are NOT freeform files. They have required frontmatter fields, expected section headings, and validation rules. Treat them accordingly.`,
+    '',
+    '1. **DO NOT write or edit markdown files directly** — not with Write, Edit, cat, echo, sed, or any other means. Use `create_document` to scaffold new documents. Use `update_section` to edit section content. Use `update_document` to change frontmatter. These tools ensure the document structure stays valid.',
+    '2. **ALWAYS call `validate` after ANY mutation** — after creating, updating frontmatter, or editing sections. No exceptions. If validation fails, fix the document before moving on.',
+    '3. **Use MCP tools to read content** — not cat, Read, or raw file access. Use `query` to fetch documents by criteria, `search_content` for full-text search, and `list_documents` for discovery.',
+    '4. **A document\'s folder prefix = its model = its contract.** The prefix determines which schema governs the file — what frontmatter fields are required, what sections are expected, and what values are valid. Do not guess. Call `get_model_info` if you are unsure.',
+    '5. **Every document MUST have a title** — either an H1 heading (`# Title`) or a `title` field in frontmatter. Validation will fail without one, unless the model sets `titleOptional: true`.',
+    '',
+  )
+
+  // Section 2: Models in This Collection
+  lines.push('## Models in This Collection', '')
+
+  for (const def of modelDefs) {
+    const name = def.name as string
+    const prefix = def.prefix as string
+    const description = def.description || ''
+    const prefixDocs = collection.available.filter((id: string) => id.startsWith(prefix + '/'))
+    const docCount = prefixDocs.length
+
+    lines.push(`### ${name}`, '')
+    lines.push(`- **Prefix:** \`${prefix}/\``)
+    lines.push(`- **Documents:** ${docCount}`)
+    if (description) lines.push(`- **Description:** ${description}`)
+    lines.push('')
+
+    // Fields
+    const fields = introspectMetaSchema(def.meta)
+    if (fields.length > 0) {
+      lines.push('**Frontmatter Fields:**', '')
+      lines.push('| Field | Type | Required | Default | Description |')
+      lines.push('|-------|------|----------|---------|-------------|')
+      for (const f of fields as any[]) {
+        const req = f.required ? 'yes' : 'no'
+        const def_val = f.defaultValue !== undefined ? `\`${JSON.stringify(f.defaultValue)}\`` : ''
+        const desc = f.description || ''
+        lines.push(`| ${f.name} | ${f.type} | ${req} | ${def_val} | ${desc} |`)
+      }
+      lines.push('')
+    }
+
+    // Sections
+    const sections = Object.entries(def.sections || {})
+    if (sections.length > 0) {
+      lines.push('**Sections:**', '')
+      for (const [key, sec] of sections as [string, any][]) {
+        lines.push(`- **${sec.heading}** (key: \`${key}\`)${sec.schema ? ' — validated' : ''}`)
+      }
+      lines.push('')
+    }
+
+    // Relationships
+    const relationships = Object.entries(def.relationships || {})
+    if (relationships.length > 0) {
+      lines.push('**Relationships:**', '')
+      for (const [key, rel] of relationships as [string, any][]) {
+        lines.push(`- \`${key}\` → ${rel.type} **${rel.model}**`)
+      }
+      lines.push('')
+    }
+
+    // Computed & Scopes
+    const computedKeys = Object.keys(def.computed || {})
+    const scopeKeys = Object.keys(def.scopes || {})
+    if (computedKeys.length > 0) lines.push(`**Computed:** ${computedKeys.join(', ')}`, '')
+    if (scopeKeys.length > 0) lines.push(`**Scopes:** ${scopeKeys.join(', ')}`, '')
+  }
+
+  // Section 3: Capability Map
+  lines.push(
+    '## Capability Map',
+    '',
+    '| Intent | Tool |',
+    '|--------|------|',
+    '| Orientation & guidance | `read_me` |',
+    '| See what models exist | `inspect` |',
+    '| Deep-dive one model | `get_model_info` |',
+    '| List documents | `list_documents` |',
+    '| Find by criteria | `query` |',
+    '| Full-text search | `search_content` |',
+    '| File-level grep | `text_search` |',
+    '| Keyword search (BM25) | `keyword_search` |',
+    '| Semantic search (embeddings) | `semantic_search` |',
+    '| Hybrid search (keyword + semantic) | `hybrid_search` |',
+    '| Create new document | `create_document` |',
+    '| Edit a section | `update_section` |',
+    '| Update frontmatter | `update_document` |',
+    '| Validate a document | `validate` |',
+    '| Delete a document | `delete_document` |',
+    '| Run a collection action | `run_action` |',
+    '',
+  )
+
+  // Section 4: Workflow
+  lines.push(
+    '## Recommended Workflow',
+    '',
+    '1. **Orientation** — Call `read_me` (this tool) at the start of every session.',
+    '2. **Discovery** — Use `list_documents` or `query` to find what exists.',
+    '3. **Reading** — Use `query` with `select` to fetch specific fields, or read a document resource.',
+    '4. **Creating** — Use `create_document` with the correct prefix. It scaffolds frontmatter and sections.',
+    '5. **Editing** — Use `update_section` for targeted section edits, `update_document` for frontmatter.',
+    '6. **Validation** — Always call `validate` after creating or editing.',
+    '',
+  )
+
+  // Section 5: Query Quick Reference
+  lines.push(
+    '## Query Quick Reference',
+    '',
+    'The `query` tool uses MongoDB-style DSL:',
+    '',
+    '- Literal value → `$eq`: `"meta.status": "active"`',
+    '- Array → `$in`: `"meta.tags": ["a", "b"]`',
+    '- Operator object: `"meta.priority": { "$gt": 5 }`',
+    '- Operators: `$eq`, `$neq`, `$in`, `$notIn`, `$gt`, `$lt`, `$gte`, `$lte`, `$contains`, `$startsWith`, `$endsWith`, `$regex`, `$exists`',
+    '- Supports `sort`, `limit`, `offset`, `select`, `scopes`, `method` (fetchAll/first/last/count)',
+    '',
+  )
+
+  // Section 6: Document Anatomy
+  lines.push(
+    '## Document Anatomy',
+    '',
+    '```markdown',
+    '---',
+    'field: value      # YAML frontmatter (model schema)',
+    '---',
+    '# Document Title  # H1 = title',
+    '',
+    '## Section Name   # H2 = sections (defined by model)',
+    '',
+    'Content here...',
+    '```',
+  )
+
+  return lines.join('\n')
+}

package/src/mcp/resources.ts

@@ -0,0 +1,89 @@
+import path from 'node:path'
+import fs from 'node:fs/promises'
+import { buildSchemaJSON } from '../cli/commands/api/helpers.js'
+
+export function registerResources(mcpServer: any, collection: any) {
+  mcpServer.resource('contentbase://schema', {
+    name: 'Collection Schema',
+    description: 'JSON schema of all registered models — fields, sections, relationships, computed properties',
+    mimeType: 'application/json',
+    handler: () => JSON.stringify(buildSchemaJSON(collection), null, 2),
+  })
+
+  mcpServer.resource('contentbase://toc', {
+    name: 'Table of Contents',
+    description: 'Markdown table of contents for all documents in the collection',
+    mimeType: 'text/markdown',
+    handler: () => collection.tableOfContents({ title: 'Table of Contents' }),
+  })
+
+  mcpServer.resource('contentbase://models-summary', {
+    name: 'Models Summary',
+    description: 'Generated README.md describing all model definitions with attributes, sections, and relationships',
+    mimeType: 'text/markdown',
+    handler: () => collection.generateModelSummary(),
+  })
+
+  mcpServer.resource('contentbase://primer', {
+    name: 'Contentbase Primer',
+    description: 'Combined teach output — models summary, table of contents, CLI reference, and API primer',
+    mimeType: 'text/markdown',
+    handler: async () => {
+      const modelsSummary = collection.generateModelSummary()
+      const toc = collection.tableOfContents({ title: 'Table of Contents' })
+
+      const packageRoot = path.resolve(import.meta.dir, '../..')
+      let primer = ''
+      let cli = ''
+      try {
+        primer = await fs.readFile(path.join(packageRoot, 'PRIMER.md'), 'utf8')
+      } catch {}
+      try {
+        cli = await fs.readFile(path.join(packageRoot, 'CLI.md'), 'utf8')
+      } catch {}
+
+      return [
+        modelsSummary.trimEnd(),
+        '',
+        '---',
+        '',
+        toc.trimEnd(),
+        '',
+        '---',
+        '',
+        cli.trimEnd(),
+        '',
+        '---',
+        '',
+        primer.trimEnd(),
+        '',
+      ].join('\n')
+    },
+  })
+
+  // Per-document resources
+  for (const pathId of collection.available) {
+    const uri = `contentbase://documents/${pathId}`
+    const doc = collection.document(pathId)
+    mcpServer.resource(uri, {
+      name: doc.title || pathId,
+      description: `Document: ${pathId}`,
+      mimeType: 'application/json',
+      handler: () => {
+        const d = collection.document(pathId)
+        const modelDef = collection.findModelDefinition(pathId)
+        return JSON.stringify({
+          id: d.id,
+          title: d.title,
+          meta: d.meta,
+          content: d.content,
+          outline: d.toOutline(),
+          model: modelDef?.name || null,
+          createdAt: d.createdAt,
+          updatedAt: d.updatedAt,
+          size: d.size,
+        }, null, 2)
+      },
+    })
+  }
+}

package/src/mcp/server.ts

@@ -0,0 +1,103 @@
+import { loadCollection } from '../cli/load-collection.js'
+import { registerResources } from './resources.js'
+import { registerQueryTools } from './tools/query.js'
+import { registerSearchTools } from './tools/search.js'
+import { registerMutationTools } from './tools/mutation.js'
+import { registerPrompts } from './prompts.js'
+
+export interface McpServerOptions {
+  transport: 'stdio' | 'http'
+  port: number
+  contentFolder?: string
+  modulePath?: string
+  mcpCompat?: 'standard' | 'codex'
+  stdioCompat?: 'standard' | 'codex' | 'auto'
+  watch?: boolean
+}
+
+export async function createMcpServer(container: any, options: McpServerOptions) {
+  const collection = await loadCollection({
+    contentFolder: options.contentFolder,
+    modulePath: options.modulePath,
+  })
+  const modelDefs = collection.modelDefinitions as any[]
+
+  console.error(`[cnotes mcp] Loaded collection: ${collection.rootPath}`)
+  console.error(`[cnotes mcp] Models: ${modelDefs.map((d: any) => d.name).join(', ') || '(none)'}`)
+  console.error(`[cnotes mcp] Documents: ${collection.available.length}`)
+
+  const mcpServer = container.server('mcp', {
+    transport: options.transport,
+    port: options.port,
+    serverName: 'contentbase',
+    serverVersion: '1.0.0',
+    mcpCompat: options.mcpCompat,
+    stdioCompat: options.stdioCompat,
+  }) as any
+
+  // Register all capabilities
+  registerResources(mcpServer, collection)
+  registerQueryTools(mcpServer, collection)
+  registerSearchTools(mcpServer, collection, container)
+  registerMutationTools(mcpServer, collection)
+  registerPrompts(mcpServer, collection)
+
+  return { mcpServer, collection }
+}
+
+export async function startMcpServer(container: any, options: McpServerOptions) {
+  const envCompat = process.env.MCP_HTTP_COMPAT?.toLowerCase()
+  const resolvedCompat = options.mcpCompat || (envCompat === 'codex' ? 'codex' : 'standard')
+  const envStdioCompat = process.env.MCP_STDIO_COMPAT?.toLowerCase()
+  const resolvedStdioCompat = options.stdioCompat
+    || (envStdioCompat === 'codex' || envStdioCompat === 'auto' ? envStdioCompat : 'standard')
+
+  const { mcpServer, collection } = await createMcpServer(container, options)
+
+  await mcpServer.start({
+    transport: options.transport,
+    port: options.port,
+    mcpCompat: options.mcpCompat,
+    stdioCompat: options.stdioCompat,
+  })
+
+  if (options.transport === 'http') {
+    console.log(`\nContentbase MCP listening on http://localhost:${options.port}/mcp`)
+    console.log(`Transport: HTTP (Streamable)`)
+    console.log(`Compatibility: ${resolvedCompat}`)
+  } else {
+    console.error(`[cnotes mcp] Server started (stdio transport)`)
+    console.error(`[cnotes mcp] Stdio compatibility: ${resolvedStdioCompat}`)
+    console.error(`[cnotes mcp] Tools: ${mcpServer._tools.size} | Resources: ${mcpServer._resources.size} | Prompts: ${mcpServer._prompts.size}`)
+  }
+
+  // File watching
+  if (options.watch !== false) {
+    const fileManager = container.feature('fileManager')
+    await fileManager.start({ rootPath: collection.rootPath })
+    await fileManager.watch()
+
+    const { debounce } = container.utils.lodash
+    const refreshCollection = debounce(async () => {
+      try {
+        const before = collection.available.length
+        await collection.load({ refresh: true })
+        const after = collection.available.length
+        if (after !== before) {
+          console.error(`[watch] Collection refreshed: ${before} → ${after} documents`)
+        }
+      } catch (err) {
+        console.error(`[watch] Refresh failed: ${(err as Error).message}`)
+      }
+    }, 500)
+
+    fileManager.on('file:change', (event: { type: string; path: string }) => {
+      if (/\.(md|mdx)$/i.test(event.path)) {
+        refreshCollection()
+      }
+    })
+    console.error(`[cnotes mcp] Watching for file changes in ${collection.rootPath}`)
+  }
+
+  return { mcpServer, collection }
+}