@sourcepress/mcp 0.1.0

package/src/__tests__/server.test.ts

@@ -0,0 +1,87 @@
+import type { EngineContext } from "@sourcepress/server";
+import { describe, expect, it, vi } from "vitest";
+import { createMcpServer } from "../server.js";
+
+function createMockEngine(): EngineContext {
+	return {
+		config: {
+			intent: { path: "intent/" },
+			// biome-ignore lint/suspicious/noExplicitAny: partial mock of EngineContext
+		} as any,
+		github: {
+			getTree: vi.fn().mockResolvedValue([]),
+			getFile: vi.fn().mockResolvedValue(null),
+			createBranch: vi.fn().mockResolvedValue("abc"),
+			createOrUpdateFile: vi.fn().mockResolvedValue({ sha: "x", commit_sha: "y" }),
+			createPR: vi.fn().mockResolvedValue({ number: 1, html_url: "https://github.com/test/pr/1" }),
+			// biome-ignore lint/suspicious/noExplicitAny: partial mock of EngineContext
+		} as any,
+		knowledge: {
+			getGraph: vi.fn().mockReturnValue(null),
+			query: vi.fn().mockReturnValue(null),
+			findStale: vi.fn().mockReturnValue([]),
+			findGaps: vi.fn().mockReturnValue([]),
+			ingest: vi.fn().mockResolvedValue({
+				path: "knowledge/test.md",
+				type: "notes",
+				quality: "draft",
+				quality_score: 5,
+				entities: [],
+				ingested_at: "2026-04-01",
+				source: "manual",
+				body: "test",
+			}),
+			buildGraph: vi.fn().mockResolvedValue({
+				entities: new Map(),
+				relations: [],
+				clusters: [],
+				built_at: "2026-04-01",
+				file_count: 0,
+			}),
+			// biome-ignore lint/suspicious/noExplicitAny: partial mock of EngineContext
+		} as any,
+		knowledgeStore: {
+			list: vi.fn().mockResolvedValue([]),
+			retrieve: vi.fn().mockResolvedValue(null),
+			// biome-ignore lint/suspicious/noExplicitAny: partial mock of EngineContext
+		} as any,
+		// biome-ignore lint/suspicious/noExplicitAny: partial mock of EngineContext
+		cache: {} as any,
+		// biome-ignore lint/suspicious/noExplicitAny: partial mock of EngineContext
+		budget: {} as any,
+		// biome-ignore lint/suspicious/noExplicitAny: partial mock of EngineContext
+		provider: {} as any,
+		listContent: vi.fn().mockResolvedValue([]),
+		getContent: vi.fn().mockResolvedValue(null),
+		getCollectionDef: vi.fn().mockImplementation((name: string) => {
+			if (name === "posts") {
+				return { name: "Blog Posts", path: "content/posts", format: "mdx", fields: {} };
+			}
+			return null;
+		}),
+		listCollections: vi.fn().mockReturnValue(["posts"]),
+	};
+}
+
+describe("MCP Server", () => {
+	it("creates MCP server instance", () => {
+		const engine = createMockEngine();
+		const server = createMcpServer(engine);
+		expect(server).toBeDefined();
+	});
+
+	it("server has correct name and version", () => {
+		const engine = createMockEngine();
+		const server = createMcpServer(engine);
+		// McpServer stores server info internally
+		expect(server).toBeDefined();
+	});
+
+	it("registers sourcepress_list_content tool", () => {
+		const engine = createMockEngine();
+		const server = createMcpServer(engine);
+		// biome-ignore lint/suspicious/noExplicitAny: accessing private MCP SDK internals for test assertion
+		const tools = (server as any)._registeredTools as Record<string, unknown>;
+		expect(Object.keys(tools)).toContain("sourcepress_list_content");
+	});
+});

package/src/index.ts

@@ -0,0 +1 @@
+export { createMcpServer } from "./server.js";

package/src/server.ts

@@ -0,0 +1,572 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import type { EngineContext } from "@sourcepress/server";
+import { z } from "zod";
+
+export function createMcpServer(engine: EngineContext): McpServer {
+	const server = new McpServer({
+		name: "sourcepress",
+		version: "0.1.0",
+	});
+
+	// --- TOOLS ---
+
+	// Content tools
+	server.tool(
+		"sourcepress_list_content",
+		"List content files, optionally filtered by collection",
+		{ collection: z.string().optional().describe("Collection name to filter by") },
+		async ({ collection }) => {
+			if (collection) {
+				const def = engine.getCollectionDef(collection);
+				if (!def) {
+					return {
+						content: [{ type: "text" as const, text: `Collection "${collection}" not found` }],
+						isError: true,
+					};
+				}
+				const files = await engine.listContent(collection);
+				return {
+					content: [
+						{
+							type: "text" as const,
+							text: JSON.stringify(
+								files.map((f) => ({
+									collection: f.collection,
+									slug: f.slug,
+									path: f.path,
+									title: f.frontmatter.title ?? f.slug,
+								})),
+								null,
+								2,
+							),
+						},
+					],
+				};
+			}
+
+			const collections = engine.listCollections();
+			const allContent = [];
+			for (const coll of collections) {
+				const files = await engine.listContent(coll);
+				allContent.push(
+					...files.map((f) => ({
+						collection: f.collection,
+						slug: f.slug,
+						path: f.path,
+						title: f.frontmatter.title ?? f.slug,
+					})),
+				);
+			}
+			return { content: [{ type: "text" as const, text: JSON.stringify(allContent, null, 2) }] };
+		},
+	);
+
+	server.tool(
+		"sourcepress_get_content",
+		"Get a single content file by collection and slug",
+		{
+			collection: z.string().describe("Collection name"),
+			slug: z.string().describe("Content slug"),
+		},
+		async ({ collection, slug }) => {
+			const file = await engine.getContent(collection, slug);
+			if (!file) {
+				return {
+					content: [
+						{ type: "text" as const, text: `Content "${slug}" not found in "${collection}"` },
+					],
+					isError: true,
+				};
+			}
+			return { content: [{ type: "text" as const, text: JSON.stringify(file, null, 2) }] };
+		},
+	);
+
+	server.tool(
+		"sourcepress_create_content",
+		"Create new content in a collection (creates a GitHub PR)",
+		{
+			collection: z.string().describe("Collection name"),
+			slug: z.string().describe("Content slug"),
+			frontmatter: z.record(z.unknown()).describe("Frontmatter key-value pairs"),
+			body: z.string().describe("Content body in markdown"),
+		},
+		async ({ collection, slug, frontmatter, body }) => {
+			const def = engine.getCollectionDef(collection);
+			if (!def) {
+				return {
+					content: [{ type: "text" as const, text: `Collection "${collection}" not found` }],
+					isError: true,
+				};
+			}
+
+			const ext = def.format === "yaml" ? "yaml" : def.format === "json" ? "json" : def.format;
+			const filePath = `${def.path}/${slug}.${ext}`;
+			const frontmatterYaml = Object.entries(frontmatter)
+				.map(([key, value]) => `${key}: ${JSON.stringify(value)}`)
+				.join("\n");
+			const fileContent = `---\n${frontmatterYaml}\n---\n\n${body}`;
+
+			const branchName = `sourcepress/create-${collection}-${slug}-${Date.now()}`;
+			await engine.github.createBranch(branchName);
+			await engine.github.createOrUpdateFile(
+				filePath,
+				fileContent,
+				`feat(${collection}): create ${slug}`,
+				branchName,
+			);
+			const pr = await engine.github.createPR(
+				`Create ${collection}: ${slug}`,
+				"Created by SourcePress MCP.",
+				branchName,
+			);
+
+			return {
+				content: [
+					{
+						type: "text" as const,
+						text: `Created PR #${pr.number}: ${pr.html_url}\nPath: ${filePath}`,
+					},
+				],
+			};
+		},
+	);
+
+	// Knowledge tools
+	server.tool(
+		"sourcepress_list_knowledge",
+		"List all knowledge files in the knowledge store",
+		{},
+		async () => {
+			const files = await engine.knowledgeStore.list();
+			const items = files.map((f) => ({
+				path: f.path,
+				type: f.type,
+				quality: f.quality,
+				quality_score: f.quality_score,
+				entities: f.entities,
+				source: f.source,
+			}));
+			return { content: [{ type: "text" as const, text: JSON.stringify(items, null, 2) }] };
+		},
+	);
+
+	server.tool(
+		"sourcepress_ingest_knowledge",
+		"Ingest new knowledge (classifies, extracts entities, stores)",
+		{
+			path: z.string().describe("Path for the knowledge file (e.g. knowledge/clients/acme.md)"),
+			body: z.string().describe("The knowledge content text"),
+			source: z
+				.enum(["manual", "url", "document", "transcript", "scrape"])
+				.optional()
+				.describe("Source type"),
+			source_url: z.string().optional().describe("Source URL if applicable"),
+		},
+		async ({ path, body, source, source_url }) => {
+			const result = await engine.knowledge.ingest(path, body, source ?? "manual", source_url);
+			return {
+				content: [
+					{
+						type: "text" as const,
+						text: JSON.stringify(
+							{
+								ingested: true,
+								path: result.path,
+								type: result.type,
+								quality: result.quality,
+								quality_score: result.quality_score,
+								entities: result.entities,
+							},
+							null,
+							2,
+						),
+					},
+				],
+			};
+		},
+	);
+
+	server.tool(
+		"sourcepress_import_from_url",
+		"Scrape a URL, extract readable content, classify, extract entities, and store as knowledge",
+		{
+			url: z.string().url().describe("The URL to scrape and import"),
+		},
+		async ({ url }) => {
+			try {
+				const result = await engine.knowledge.importUrl(url);
+				return {
+					content: [
+						{
+							type: "text" as const,
+							text: JSON.stringify(
+								{
+									imported: true,
+									path: result.path,
+									type: result.type,
+									quality: result.quality,
+									quality_score: result.quality_score,
+									entities: result.entities,
+									source_url: result.source_url,
+								},
+								null,
+								2,
+							),
+						},
+					],
+				};
+			} catch (error) {
+				return {
+					content: [
+						{
+							type: "text" as const,
+							text: `Failed to import ${url}: ${error instanceof Error ? error.message : String(error)}`,
+						},
+					],
+					isError: true,
+				};
+			}
+		},
+	);
+
+	server.tool(
+		"sourcepress_import_batch",
+		"Import multiple URLs as a background job. Returns a job_id to track progress.",
+		{
+			urls: z.array(z.string().url()).min(1).describe("List of URLs to import"),
+		},
+		async ({ urls }) => {
+			if (!engine.jobs) {
+				return {
+					content: [{ type: "text" as const, text: "Job system not configured" }],
+					isError: true,
+				};
+			}
+			const jobId = await engine.jobs.enqueue({
+				type: "import-batch",
+				params: { urls },
+			});
+			const status = await engine.jobs.status(jobId);
+			return {
+				content: [
+					{
+						type: "text" as const,
+						text: JSON.stringify(
+							{
+								started: true,
+								job_id: jobId,
+								url_count: urls.length,
+								status: status?.status ?? "queued",
+							},
+							null,
+							2,
+						),
+					},
+				],
+			};
+		},
+	);
+
+	server.tool(
+		"sourcepress_import_sitemap",
+		"Fetch and parse a sitemap, returning URL sections for interactive selection. Use import_sitemap_run to start the actual import after the user selects sections.",
+		{
+			url: z.string().url().describe("Sitemap URL (e.g. https://example.com/sitemap.xml)"),
+		},
+		async ({ url }) => {
+			try {
+				const result = await engine.knowledge.parseSitemap(url);
+				return {
+					content: [
+						{
+							type: "text" as const,
+							text: JSON.stringify(
+								{
+									sitemap_url: result.sitemap_url,
+									total_urls: result.total_urls,
+									sections: result.sections.map((s) => ({
+										name: s.name,
+										pattern: s.pattern,
+										count: s.count,
+									})),
+								},
+								null,
+								2,
+							),
+						},
+					],
+				};
+			} catch (error) {
+				return {
+					content: [
+						{
+							type: "text" as const,
+							text: `Failed to parse sitemap: ${error instanceof Error ? error.message : String(error)}`,
+						},
+					],
+					isError: true,
+				};
+			}
+		},
+	);
+
+	server.tool(
+		"sourcepress_import_sitemap_run",
+		"Run a sitemap import with include/exclude filters. Creates a background job. Use import_sitemap first to see available sections.",
+		{
+			sitemap_url: z.string().url().describe("The sitemap URL (same as used in import_sitemap)"),
+			include: z
+				.array(z.string())
+				.optional()
+				.describe('Path patterns to include (e.g. ["/services/*", "/cases/*"])'),
+			exclude: z
+				.array(z.string())
+				.optional()
+				.describe('Path patterns to exclude (e.g. ["/blog/*"])'),
+		},
+		async ({ sitemap_url, include, exclude }) => {
+			if (!engine.jobs) {
+				return {
+					content: [{ type: "text" as const, text: "Job system not configured" }],
+					isError: true,
+				};
+			}
+			const jobId = await engine.jobs.enqueue({
+				type: "import-sitemap",
+				params: { sitemap_url, include, exclude },
+			});
+			const status = await engine.jobs.status(jobId);
+			return {
+				content: [
+					{
+						type: "text" as const,
+						text: JSON.stringify(
+							{
+								started: true,
+								job_id: jobId,
+								sitemap_url,
+								include: include ?? [],
+								exclude: exclude ?? [],
+								status: status?.status ?? "queued",
+							},
+							null,
+							2,
+						),
+					},
+				],
+			};
+		},
+	);
+
+	// Graph tools
+	server.tool(
+		"sourcepress_query_graph",
+		"Query the knowledge graph for an entity by name or alias",
+		{ name: z.string().describe("Entity name or alias to search for") },
+		async ({ name }) => {
+			const result = engine.knowledge.query(name);
+			if (!result) {
+				return {
+					content: [
+						{
+							type: "text" as const,
+							text: `Entity "${name}" not found. Graph may need rebuilding.`,
+						},
+					],
+					isError: true,
+				};
+			}
+			return {
+				content: [
+					{
+						type: "text" as const,
+						text: JSON.stringify(
+							{
+								entity: result.entity,
+								relations: result.relations,
+								related_entities: result.related_entities,
+								files: result.files,
+							},
+							null,
+							2,
+						),
+					},
+				],
+			};
+		},
+	);
+
+	server.tool(
+		"sourcepress_find_gaps",
+		"Find knowledge gaps — entities with knowledge but no content",
+		{},
+		async () => {
+			const collections = engine.listCollections();
+			const allContent = [];
+			for (const coll of collections) {
+				const files = await engine.listContent(coll);
+				allContent.push(...files);
+			}
+			const gaps = engine.knowledge.findGaps(allContent);
+			return { content: [{ type: "text" as const, text: JSON.stringify(gaps, null, 2) }] };
+		},
+	);
+
+	server.tool(
+		"sourcepress_find_stale",
+		"Find stale content — content whose source knowledge has been updated",
+		{},
+		async () => {
+			const collections = engine.listCollections();
+			const allContent = [];
+			for (const coll of collections) {
+				const files = await engine.listContent(coll);
+				allContent.push(...files);
+			}
+			const knowledgeFiles = await engine.knowledgeStore.list();
+			const timestamps: Record<string, string> = {};
+			for (const f of knowledgeFiles) {
+				timestamps[f.path] = f.ingested_at;
+			}
+			const stale = engine.knowledge.findStale(allContent, timestamps);
+			return { content: [{ type: "text" as const, text: JSON.stringify(stale, null, 2) }] };
+		},
+	);
+
+	server.tool(
+		"sourcepress_score_content",
+		"Score content against intent using AI",
+		{
+			collection: z.string().describe("Collection name"),
+			slug: z.string().describe("Content slug"),
+			intent: z.string().describe("Intent text to score against"),
+		},
+		async ({ collection, slug, intent }) => {
+			const { score } = await import("@sourcepress/ai");
+			const file = await engine.getContent(collection, slug);
+			if (!file) {
+				return {
+					content: [
+						{ type: "text" as const, text: `Content "${slug}" not found in "${collection}"` },
+					],
+					isError: true,
+				};
+			}
+			const result = await score(
+				{ content: file.body, intent, collection_name: collection },
+				engine.provider,
+				engine.budget,
+			);
+			return {
+				content: [
+					{
+						type: "text" as const,
+						text: JSON.stringify(
+							{
+								score: result.score,
+								issues: result.issues,
+								strengths: result.strengths,
+							},
+							null,
+							2,
+						),
+					},
+				],
+			};
+		},
+	);
+
+	server.tool(
+		"sourcepress_rebuild_graph",
+		"Rebuild the knowledge graph from all knowledge files",
+		{},
+		async () => {
+			const graph = await engine.knowledge.buildGraph();
+			return {
+				content: [
+					{
+						type: "text" as const,
+						text: JSON.stringify(
+							{
+								rebuilt: true,
+								entity_count: graph.entities.size,
+								relation_count: graph.relations.length,
+								cluster_count: graph.clusters.length,
+								file_count: graph.file_count,
+								built_at: graph.built_at,
+							},
+							null,
+							2,
+						),
+					},
+				],
+			};
+		},
+	);
+
+	// --- RESOURCES ---
+
+	server.resource(
+		"schema",
+		"sourcepress://schema",
+		{ description: "Full SourcePress schema — all collections with fields and formats" },
+		async () => {
+			const collections = engine.listCollections();
+			const schema: Record<string, unknown> = {};
+			for (const name of collections) {
+				const def = engine.getCollectionDef(name);
+				if (def)
+					schema[name] = { name: def.name, path: def.path, format: def.format, fields: def.fields };
+			}
+			return {
+				contents: [
+					{
+						uri: "sourcepress://schema",
+						text: JSON.stringify(schema, null, 2),
+						mimeType: "application/json",
+					},
+				],
+			};
+		},
+	);
+
+	server.resource(
+		"graph",
+		"sourcepress://graph",
+		{ description: "Knowledge graph summary — entities, relations, clusters" },
+		async () => {
+			const graph = engine.knowledge.getGraph();
+			if (!graph) {
+				return {
+					contents: [
+						{
+							uri: "sourcepress://graph",
+							text: '{"status":"empty","message":"No graph built yet"}',
+							mimeType: "application/json",
+						},
+					],
+				};
+			}
+			const summary = {
+				entity_count: graph.entities.size,
+				relation_count: graph.relations.length,
+				cluster_count: graph.clusters.length,
+				file_count: graph.file_count,
+				built_at: graph.built_at,
+				entities: Array.from(graph.entities.keys()),
+			};
+			return {
+				contents: [
+					{
+						uri: "sourcepress://graph",
+						text: JSON.stringify(summary, null, 2),
+						mimeType: "application/json",
+					},
+				],
+			};
+		},
+	);
+
+	return server;
+}

package/src/stdio.ts

@@ -0,0 +1,43 @@
+#!/usr/bin/env node
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import type { SourcePressConfig } from "@sourcepress/core";
+import { createEngine } from "@sourcepress/server";
+import { createMcpServer } from "./server.js";
+
+async function main() {
+	const githubToken = process.env.GITHUB_TOKEN;
+	if (!githubToken) {
+		console.error("GITHUB_TOKEN environment variable is required");
+		process.exit(1);
+	}
+
+	const config: SourcePressConfig = {
+		repository: {
+			owner: process.env.GITHUB_OWNER ?? "sourcepress",
+			repo: process.env.GITHUB_REPO ?? "demo",
+			branch: process.env.GITHUB_BRANCH ?? "main",
+		},
+		ai: {
+			provider: (process.env.AI_PROVIDER as "anthropic" | "openai" | "local") ?? "anthropic",
+			model: process.env.AI_MODEL ?? "claude-sonnet-4-5-20250514",
+		},
+		collections: {},
+		knowledge: { path: "knowledge/", graph: { backend: "local" } },
+		intent: { path: "intent/" },
+	};
+
+	const engine = await createEngine({
+		config,
+		githubToken,
+		aiApiKey: process.env.AI_API_KEY,
+	});
+
+	const mcpServer = createMcpServer(engine);
+	const transport = new StdioServerTransport();
+	await mcpServer.connect(transport);
+}
+
+main().catch((err) => {
+	console.error("MCP server error:", err);
+	process.exit(1);
+});

package/tsconfig.json

@@ -0,0 +1,8 @@
+{
+	"extends": "../../tsconfig.json",
+	"compilerOptions": {
+		"outDir": "dist",
+		"rootDir": "src"
+	},
+	"include": ["src"]
+}