feat: set up mcp for docs (#5)

### Explanation

_No response_

### Issue

_No response_

### Attestations

- [x] I have read and agree to the [Code of Conduct](https://docs.nhcarrigan.com/community/coc/)
- [x] I have read and agree to the [Community Guidelines](https://docs.nhcarrigan.com/community/guide/).
- [x] My contribution complies with the [Contributor Covenant](https://docs.nhcarrigan.com/dev/covenant/).

### Dependencies

- [x] I have pinned the dependencies to a specific patch version.

### Style

- [x] I have run the linter and resolved any errors.
- [x] My pull request uses an appropriate title, matching the conventional commit standards.
- [x] My scope of feat/fix/chore/etc. correctly matches the nature of changes in my pull request.

### Tests

- [ ] My contribution adds new code, and I have added tests to cover it.
- [ ] My contribution modifies existing code, and I have updated the tests to reflect these changes.
- [ ] All new and existing tests pass locally with my changes.
- [ ] Code coverage remains at or above the configured threshold.

### Documentation

_No response_

### Versioning

_No response_

Reviewed-on: #5
Co-authored-by: Naomi Carrigan <commits@nhcarrigan.com>
Co-committed-by: Naomi Carrigan <commits@nhcarrigan.com>

server/getDocs.ts

@@ -0,0 +1,76 @@
+/**
+ * @copyright nhcarrigan
+ * @license Naomi's Public License
+ * @author Naomi Carrigan
+ */
+
+/**
+ * This script fetches our documentation from our repository,
+ * compiles it into an MCP format, and writes it to a JSON file.
+ * It is intended to run automatically as part of the build process.
+ */
+
+import fs from "node:fs/promises";
+import path from "node:path";
+import matter from "gray-matter";
+import { promisify } from "node:util";
+import { exec } from "node:child_process";
+
+const execAsync = promisify(exec);
+
+const docsDirectory = path.resolve(process.cwd(), "temp-docs");
+const docsPath = path.resolve(process.cwd(), "temp-docs", "src", "content", "docs")
+
+async function walk(directory: string): Promise<Array<string>> {
+  const dirents = await fs.readdir(directory, { withFileTypes: true });
+  const files = await Promise.all(
+    dirents.map(async (dirent) => {
+      const result = path.resolve(directory, dirent.name);
+      return dirent.isDirectory() ? await walk(result) : result;
+    })
+  );
+  return files.flat();
+}
+
+await execAsync(`git clone https://git.nhcarrigan.com/nhcarrigan/docs.git ${docsDirectory}`, {
+  cwd: process.cwd(),
+  stdio: "inherit",
+});
+
+const files = await walk(docsPath);
+const markdownFiles = files.filter((f) => {
+  return f.endsWith(".md");
+});
+
+const results = await Promise.all(
+  markdownFiles.map(async (file) => {
+    const raw = await fs.readFile(file, "utf-8");
+    const { content, data } = matter(raw);
+
+    // Split content by header blocks (basic chunking)
+    const chunks = content.split(/^#+\s+/gm).map((chunk, index) => {
+      return {
+        content: chunk.trim(),
+        file: path.relative(docsDirectory, file),
+        id: `${path.relative(docsDirectory, file)}::${index}`,
+        metadata: data,
+        title:
+          index === 0 ? "(intro)" : chunk.split("\n")[0]?.trim() ?? "Unknown",
+        url: `https://docs.nhcarrigan.com/${path
+          .relative(docsPath, file)
+          .replace(/\.md$/, "").replace(/\/$/, "")}#${index === 0 ? "" : chunk.split("\n")[0]?.trim().toLowerCase().replace(/\s+/g, "-").replace(/\./g, "")}`,
+      };
+    });
+
+    return chunks;
+  })
+);
+
+const flat = results.flat();
+
+await fs.writeFile(
+  path.resolve(process.cwd(), "src", "data", "docs.json"),
+  JSON.stringify(flat, null, 2)
+);
+
+await fs.rm(docsDirectory, { recursive: true, force: true });

server/package.json

@@ -7,7 +7,7 @@
   "scripts": {
     "lint": "eslint ./src --max-warnings 0",
     "dev": "NODE_ENV=dev op run --env-file=./dev.env -- tsx watch ./src/index.ts",
-    "build": "tsc",
+    "build": "tsx ./getDocs.ts && tsc",
     "start": "op run --env-file=./prod.env -- node ./prod/index.js",
     "test": "echo 'No tests yet' && exit 0"
   },
@@ -19,7 +19,8 @@
     "@fastify/cors": "11.0.1",
     "@nhcarrigan/logger": "1.0.0",
     "@prisma/client": "6.11.1",
-    "fastify": "5.4.0"
+    "fastify": "5.4.0",
+    "gray-matter": "4.0.3"
   },
   "devDependencies": {
     "@types/node": "24.0.10",

server/src/config/routesWithoutCors.ts

@@ -12,4 +12,5 @@ export const routesWithoutCors = [
   "/",
   "/announcement",
   "/health",
+  "/mcp",
 ];

server/src/index.ts

@@ -10,6 +10,7 @@ import { corsHook } from "./hooks/cors.js";
 import { ipHook } from "./hooks/ips.js";
 import { announcementRoutes } from "./routes/announcement.js";
 import { baseRoutes } from "./routes/base.js";
+import { mcpRoutes } from "./routes/mcp.js";
 import { logger } from "./utils/logger.js";
 
 const server = fastify({
@@ -32,6 +33,7 @@ server.addHook("preHandler", ipHook);
 
 server.register(baseRoutes);
 server.register(announcementRoutes);
+server.register(mcpRoutes);
 
 server.listen({ port: 20_000 }, (error) => {
   if (error) {

server/src/routes/mcp.ts

@@ -0,0 +1,21 @@
+/**
+ * @copyright nhcarrigan
+ * @license Naomi's Public License
+ * @author Naomi Carrigan
+ */
+
+import documentationData from "../data/docs.json";
+import type { FastifyPluginAsync } from "fastify";
+
+/**
+ * Mounts the Model Context Protocol routes for the application. These routes
+ * should not require CORS, as they are used by external services
+ * such as ChatGPT.
+ * @param server - The Fastify server instance.
+ */
+export const mcpRoutes: FastifyPluginAsync = async(server) => {
+  server.get("/mcp", async(_request, reply) => {
+    return await reply.status(200).send(documentationData);
+  });
+};
+

server/tsconfig.json

@@ -3,5 +3,7 @@
     "compilerOptions": {
         "rootDir": "./src",
         "outDir": "./prod",
-    }
+        "resolveJsonModule": true
+    },
+    "exclude": ["./getDocs.ts"]
 }