feat(cms): add getResources MCP tool for markdown resources (#43)

Author: jhb-dev

cms/next.config.ts

@@ -5,6 +5,13 @@ const nextConfig: NextConfig = {
   experimental: {
     turbopackFileSystemCacheForDev: true,
   },
+  // The `getResources` MCP tool reads markdown files from `cms/resources/` at runtime
+  // (see `src/mcp/resources.ts`). The directory is scanned dynamically, so static
+  // tracing can't detect it — force-include the files into the serverless function
+  // that serves Payload's API (and thus the MCP endpoint) under `api/[...slug]`.
+  outputFileTracingIncludes: {
+    '/api/[...slug]': ['./resources/**/*.md'],
+  },
   redirects: async () => [
     {
       destination: '/admin',

docs/writing-style-guide.md cms/resources/writing-style-guide.mddocs/writing-style-guide.md renamed to cms/resources/writing-style-guide.md

@@ -1,3 +1,8 @@
+---
+title: Writing Style & Tonality Guide
+description: Voice, structure, formatting, linking and SEO rules for JHB Software articles (en/de).
+---
+
 # Writing Style & Tonality Guide — JHB Software Articles
 
 For articles in the `articles` collection, in both `en` and `de`.

cms/src/mcp/resources.ts

@@ -0,0 +1,99 @@
+import { readdir, readFile } from 'fs/promises'
+import { join } from 'path'
+
+// Markdown resources (e.g. the writing style guide) live as plain `.md` files in
+// `cms/resources/` so they stay versioned and browsable in Git. They are read at
+// runtime and exposed through the `getResources` MCP tool.
+//
+// `process.cwd()` is the cms project root both locally and in the Vercel serverless
+// function. The files are not statically reachable (we scan the directory at runtime),
+// so they are force-included into the function bundle via `outputFileTracingIncludes`
+// in `next.config.ts` — keep that entry in sync with this directory.
+const RESOURCES_DIR = join(process.cwd(), 'resources')
+
+// Only simple, lowercase-kebab slugs are valid. Enforced before building a file path
+// to prevent path traversal, since the slug originates from an MCP tool argument.
+const SLUG_PATTERN = /^[a-z0-9-]+$/
+
+export type ResourceMeta = {
+  slug: string
+  title: string
+  description: string
+}
+
+export type Resource = ResourceMeta & {
+  content: string
+}
+
+/**
+ * Minimal YAML front matter parser. Handles the simple `key: value` scalars we use
+ * (`title`, `description`) — not nested structures. Returns the parsed key/value map
+ * and the markdown body with the front matter block stripped.
+ */
+function parseFrontMatter(raw: string): { data: Record<string, string>; body: string } {
+  const match = /^---\r?\n([\s\S]*?)\r?\n---\r?\n?/.exec(raw)
+  if (!match) return { body: raw, data: {} }
+
+  const data: Record<string, string> = {}
+  for (const line of match[1].split(/\r?\n/)) {
+    const separator = line.indexOf(':')
+    if (separator === -1) continue
+    const key = line.slice(0, separator).trim()
+    if (!key) continue
+    // Strip surrounding single/double quotes from the value.
+    const value = line
+      .slice(separator + 1)
+      .trim()
+      .replace(/^['"]|['"]$/g, '')
+    data[key] = value
+  }
+
+  return { body: raw.slice(match[0].length), data }
+}
+
+function toMeta(slug: string, data: Record<string, string>): ResourceMeta {
+  return {
+    description: data.description ?? '',
+    slug,
+    title: data.title ?? slug,
+  }
+}
+
+/** Lists all available resources with their front matter metadata. */
+export async function listResources(): Promise<ResourceMeta[]> {
+  let entries: string[]
+  try {
+    entries = await readdir(RESOURCES_DIR)
+  } catch {
+    return []
+  }
+
+  const slugs = entries.filter((name) => name.endsWith('.md')).map((name) => name.slice(0, -3))
+
+  const resources = await Promise.all(
+    slugs.map(async (slug) => {
+      const raw = await readFile(join(RESOURCES_DIR, `${slug}.md`), 'utf-8')
+      return toMeta(slug, parseFrontMatter(raw).data)
+    }),
+  )
+
+  return resources.sort((a, b) => a.slug.localeCompare(b.slug))
+}
+
+/**
+ * Reads a single resource by slug, returning its metadata and markdown body (front
+ * matter stripped). Returns `null` for an invalid or unknown slug.
+ */
+export async function readResource(slug: string): Promise<Resource | null> {
+  if (!SLUG_PATTERN.test(slug)) return null
+
+  let raw: string
+  try {
+    raw = await readFile(join(RESOURCES_DIR, `${slug}.md`), 'utf-8')
+  } catch {
+    return null
+  }
+
+  const { body, data } = parseFrontMatter(raw)
+  return { ...toMeta(slug, data), content: body.trim() }
+}

cms/src/payload.config.ts

@@ -64,6 +64,7 @@ import Footer from './globals/Footer'
 import Header from './globals/Header'
 import Labels from './globals/Labels'
 import { mcpOverrideAuth } from './mcp/overrideAuth'
+import { listResources, readResource } from './mcp/resources'
 import { authenticated } from './shared/access/authenticated'
 import { CollectionGroups } from './shared/CollectionGroups'
 import { customTranslations } from './shared/customTranslations'
@@ -173,6 +174,15 @@ const getPageUrlParameters = {
     .describe('Whether to generate a preview URL. Defaults to true.'),
 } satisfies z.ZodRawShape
 
+const getResourcesParameters = {
+  slug: z
+    .string()
+    .optional()
+    .describe(
+      'Slug of a single resource (the markdown filename without its `.md` extension). Omit to list all available resources.',
+    ),
+} satisfies z.ZodRawShape
+
 // Lifted out of the `buildConfig` literal and annotated with the concrete
 // `MCPPluginConfig` type so the tool definition is type-checked directly against
 // the plugin's contract and keeps the `buildConfig` call readable.
@@ -283,6 +293,47 @@ const mcpPluginConfig: MCPPluginConfig = {
         name: 'getPageUrl',
         parameters: getPageUrlParameters as unknown as MCPToolParameters,
       },
+      // The MCP spec has a native "resources" primitive, and this plugin's server
+      // exposes it — but claude.ai (a primary client here) only supports MCP *tools*,
+      // not resources. So we surface our markdown resources through this custom tool
+      // instead. The files live in `cms/resources/` (see `./mcp/resources.ts`), which
+      // keeps them available in Git and over MCP from a single source.
+      {
+        description:
+          'Read project resources stored as markdown (e.g. the writing style & tonality guide). Without a `slug`, returns the list of available resources as JSON (`{ slug, title, description }`). With a `slug`, returns the full markdown content of that resource.',
+        handler: async (args) => {
+          const text = (t: string) => ({ content: [{ text: t, type: 'text' as const }] })
+          try {
+            const { slug } = z.object(getResourcesParameters).parse(args)
+
+            if (slug === undefined) {
+              return text(JSON.stringify(await listResources()))
+            }
+
+            const resource = await readResource(slug)
+            if (!resource) {
+              const available = await listResources()
+              return text(
+                JSON.stringify({
+                  availableSlugs: available.map((r) => r.slug),
+                  error: `No resource with slug "${slug}".`,
+                }),
+              )
+            }
+
+            return text(resource.content)
+          } catch (err) {
+            return text(
+              JSON.stringify({
+                details: err instanceof Error ? err.message : String(err),
+                error: 'Failed to read resource',
+              }),
+            )
+          }
+        },
+        name: 'getResources',
+        parameters: getResourcesParameters as unknown as MCPToolParameters,
+      },
     ],
   },
   overrideAuth: (req, getDefault) => mcpOverrideAuth(req, getDefault),