pi-harness-runtime 0.9.2 → 0.9.5

package/packages/mcp-adapter/src/server.ts

@@ -0,0 +1,273 @@
+/**
+ * MCP Adapter — STDIO Server (RFC-0068)
+ *
+ * Implements MCP Protocol 2024-11-05 over STDIO.
+ * Reads JSON-RPC requests from stdin, writes responses to stdout.
+ */
+
+import { HARNESS_TOOLS } from "./tools.js";
+import type {
+	MCPRequest,
+	MCPResponse,
+	MCPServerOptions,
+	InitializeResult,
+	MCPResource,
+	MCPPrompt,
+	ToolCallParams,
+} from "./types.js";
+
+let initialized = false;
+
+export async function createMCPServer(
+	options: MCPServerOptions = {},
+): Promise<void> {
+	const serverName = options.name ?? "pi-harness";
+	const serverVersion = options.version ?? "0.9.4";
+	const protocolVersion = "2024-11-05" as const;
+
+	// Read JSON-RPC requests from stdin
+	let buffer = "";
+	process.stdin.setEncoding("utf-8");
+
+	process.stdin.on("data", async (chunk: string) => {
+		buffer += chunk;
+
+		// Split on newlines (JSON-RPC messages)
+		const lines = buffer.split("\n");
+		buffer = lines.pop() ?? "";
+
+		for (const line of lines) {
+			if (!line.trim()) continue;
+			try {
+				const request = JSON.parse(line) as MCPRequest;
+				const response = handleRequestSync(
+					request,
+					serverName,
+					serverVersion,
+					protocolVersion,
+				);
+				if (response) {
+					process.stdout.write(JSON.stringify(response) + "\n");
+				}
+			} catch (err) {
+				const msg = err instanceof Error ? err.message : "Parse error";
+				const errorResponse: MCPResponse = {
+					jsonrpc: "2.0",
+					id: 0,
+					error: { code: -32700, message: msg },
+				};
+				process.stdout.write(JSON.stringify(errorResponse) + "\n");
+			}
+		}
+	});
+
+	process.stdin.on("end", () => {
+		if (buffer.trim()) {
+			try {
+				const request = JSON.parse(buffer) as MCPRequest;
+				const response = handleRequestSync(
+					request,
+					serverName,
+					serverVersion,
+					protocolVersion,
+				);
+				if (response) {
+					process.stdout.write(JSON.stringify(response) + "\n");
+				}
+			} catch {
+				// ignore
+			}
+		}
+	});
+}
+
+function handleRequestSync(
+	req: MCPRequest,
+	serverName: string,
+	serverVersion: string,
+	protocolVersion: string,
+): MCPResponse | null {
+	const { method, id } = req;
+
+	// Initialize — must be first
+	if (method === "initialize") {
+		initialized = true;
+		const result: InitializeResult = {
+			protocolVersion: protocolVersion as InitializeResult["protocolVersion"],
+			capabilities: {
+				tools: { listChanged: false },
+				resources: { subscribe: false, listChanged: false },
+				prompts: { listChanged: false },
+			},
+			serverInfo: { name: serverName, version: serverVersion },
+		};
+		return { jsonrpc: "2.0", id, result };
+	}
+
+	// Every request after initialize needs initialized notification
+	if (!initialized && method !== "initialize") {
+		return {
+			jsonrpc: "2.0",
+			id,
+			error: { code: -32602, message: "Server not initialized" },
+		};
+	}
+
+	switch (method) {
+		case "tools/list": {
+			const result = { tools: HARNESS_TOOLS };
+			return { jsonrpc: "2.0", id, result };
+		}
+
+		case "tools/call": {
+			const params = req.params as unknown as ToolCallParams;
+			if (!params.name) {
+				return {
+					jsonrpc: "2.0",
+					id,
+					error: { code: -32602, message: "Missing tool name" },
+				};
+			}
+			const result = handleToolCallSync(params.name, params.arguments);
+			return { jsonrpc: "2.0", id, result };
+		}
+
+		case "resources/list": {
+			const resources: MCPResource[] = [
+				{
+					uri: "harness://skills",
+					name: "Harness Skills",
+					description: "List of all registered skills",
+				},
+				{
+					uri: "harness://capabilities",
+					name: "Capabilities",
+					description: "Current capability registry",
+				},
+			];
+			const result = { resources };
+			return { jsonrpc: "2.0", id, result };
+		}
+
+		case "prompts/list": {
+			const prompts: MCPPrompt[] = [
+				{
+					name: "analyze_project",
+					description: "Full project analysis with recommendations",
+				},
+				{
+					name: "review_code",
+					description: "Code review with context from workspace",
+				},
+			];
+			const result = { prompts };
+			return { jsonrpc: "2.0", id, result };
+		}
+
+		case "ping": {
+			return { jsonrpc: "2.0", id, result: null };
+		}
+
+		default:
+			return {
+				jsonrpc: "2.0",
+				id,
+				error: { code: -32601, message: `Method not found: ${method}` },
+			};
+	}
+}
+
+/** Synchronous tool call wrapper (tool handlers are sync for MCP) */
+function handleToolCallSync(
+	toolName: string,
+	args?: Record<string, unknown>,
+): { content: Array<{ type: string; text: string }>; isError?: boolean } {
+	try {
+		switch (toolName) {
+			case "analyze_workspace": {
+				const { path } = (args ?? {}) as { path: string };
+				const fs = require("fs");
+				if (!fs.existsSync(path)) {
+					return {
+						content: [{ type: "text", text: `Path does not exist: ${path}` }],
+						isError: true,
+					};
+				}
+				const files = fs.readdirSync(path);
+				const frameworks: string[] = [];
+				if (files.includes("package.json")) frameworks.push("node");
+				if (files.includes("go.mod")) frameworks.push("go");
+				if (
+					files.includes("pyproject.toml") ||
+					files.includes("requirements.txt")
+				)
+					frameworks.push("python");
+				if (files.includes("composer.json")) frameworks.push("php");
+				if (
+					files.includes("next.config.js") ||
+					files.includes("next.config.ts")
+				)
+					frameworks.push("nextjs");
+				if (files.includes("vite.config.ts")) frameworks.push("react-vite");
+				if (files.includes("manage.py")) frameworks.push("django");
+				return {
+					content: [
+						{
+							type: "text",
+							text: JSON.stringify(
+								{ path, frameworks, fileCount: files.length },
+								null,
+								2,
+							),
+						},
+					],
+				};
+			}
+			case "search_memory":
+				return {
+					content: [
+						{
+							type: "text",
+							text: JSON.stringify({
+								query: (args as { query: string })?.query,
+								results: [],
+								note: "Stub — integrate with memory-engine at runtime",
+							}),
+						},
+					],
+				};
+			case "list_skills":
+				return {
+					content: [
+						{
+							type: "text",
+							text: JSON.stringify({
+								skills: [],
+								note: "Stub — integrate with skill-registry at runtime",
+							}),
+						},
+					],
+				};
+			case "invoke_skill":
+				return {
+					content: [
+						{
+							type: "text",
+							text: JSON.stringify({
+								skill: (args as { name: string })?.name,
+								note: "Stub — integrate with skill-registry at runtime",
+							}),
+						},
+					],
+				};
+			default:
+				return {
+					content: [{ type: "text", text: `Unknown tool: ${toolName}` }],
+					isError: true,
+				};
+		}
+	} catch (err) {
+		const msg = err instanceof Error ? err.message : String(err);
+		return { content: [{ type: "text", text: msg }], isError: true };
+	}
+}

package/packages/mcp-adapter/src/tools.ts

@@ -0,0 +1,220 @@
+/// <reference types="node" />
+
+/**
+ * MCP Adapter — Tool Definitions (RFC-0068)
+ *
+ * Exposes 4 core harness capabilities as MCP tools.
+ */
+
+import type { MCPTool, ToolCallResult } from "./types.js";
+
+export const HARNESS_TOOLS: MCPTool[] = [
+	{
+		name: "analyze_workspace",
+		description:
+			"Analyze a codebase directory to detect framework, structure, and dependencies",
+		inputSchema: {
+			type: "object",
+			properties: {
+				path: {
+					type: "string",
+					description: "Absolute path to workspace directory",
+				},
+				framework: {
+					type: "string",
+					description: "Force specific framework detection",
+				},
+			},
+			required: ["path"],
+		},
+	},
+	{
+		name: "search_memory",
+		description:
+			"Search the harness persistent memory store for relevant knowledge",
+		inputSchema: {
+			type: "object",
+			properties: {
+				query: { type: "string", description: "Search query" },
+				limit: { type: "number", description: "Max results (default: 5)" },
+			},
+			required: ["query"],
+		},
+	},
+	{
+		name: "list_skills",
+		description:
+			"List all registered harness skills with their triggers and capabilities",
+		inputSchema: {
+			type: "object",
+			properties: {
+				capability: {
+					type: "string",
+					description: "Filter by capability type",
+				},
+			},
+		},
+	},
+	{
+		name: "invoke_skill",
+		description: "Invoke a named harness skill with a trigger",
+		inputSchema: {
+			type: "object",
+			properties: {
+				name: { type: "string", description: "Skill name to invoke" },
+				trigger: {
+					type: "object",
+					description: "Trigger object with type and value",
+					properties: {
+						type: { type: "string", enum: ["keyword", "intent", "pattern"] },
+						value: { type: "string" },
+						confidence: { type: "number" },
+					},
+					required: ["type", "value"],
+				},
+				context: { type: "object", description: "Optional context overrides" },
+			},
+			required: ["name", "trigger"],
+		},
+	},
+];
+
+/**
+ * Tool handler function — maps MCP tool name to harness capability
+ */
+export async function handleToolCall(
+	toolName: string,
+	args?: Record<string, unknown>,
+): Promise<ToolCallResult> {
+	try {
+		switch (toolName) {
+			case "analyze_workspace":
+				return handleAnalyzeWorkspace(args as unknown as AnalyzeArgs);
+			case "search_memory":
+				return handleSearchMemory(args as unknown as SearchArgs);
+			case "list_skills":
+				return handleListSkills(args as unknown as ListSkillsArgs);
+			case "invoke_skill":
+				return handleInvokeSkill(args as unknown as InvokeSkillArgs);
+			default:
+				return {
+					content: [{ type: "text", text: `Unknown tool: ${toolName}` }],
+					isError: true,
+				};
+		}
+	} catch (err) {
+		const msg = err instanceof Error ? err.message : String(err);
+		return { content: [{ type: "text", text: msg }], isError: true };
+	}
+}
+
+interface AnalyzeArgs {
+	path: string;
+	framework?: string;
+}
+interface SearchArgs {
+	query: string;
+	limit?: number;
+}
+interface ListSkillsArgs {
+	capability?: string;
+}
+interface InvokeSkillArgs {
+	name: string;
+	trigger: { type: string; value: string; confidence?: number };
+	context?: Record<string, unknown>;
+}
+
+async function handleAnalyzeWorkspace(
+	args: AnalyzeArgs,
+): Promise<ToolCallResult> {
+	const { path } = args;
+	const fs = await import("node:fs");
+	const pathModule = await import("node:path");
+
+	if (!fs.existsSync(path)) {
+		return {
+			content: [{ type: "text", text: `Path does not exist: ${path}` }],
+			isError: true,
+		};
+	}
+
+	// Basic framework detection from filesystem
+	const files = fs.readdirSync(path);
+	const frameworks: string[] = [];
+	if (files.includes("package.json")) frameworks.push("node");
+	if (files.includes("go.mod")) frameworks.push("go");
+	if (files.includes("Cargo.toml")) frameworks.push("rust");
+	if (files.includes("pyproject.toml") || files.includes("requirements.txt"))
+		frameworks.push("python");
+	if (files.includes("composer.json")) frameworks.push("php");
+	if (
+		files.includes("frappe-bench") ||
+		fs.existsSync(pathModule.join(path, "sites"))
+	) {
+		frameworks.push("frappe");
+	}
+	if (files.includes("next.config.js") || files.includes("next.config.ts"))
+		frameworks.push("nextjs");
+	if (files.includes("vite.config.ts")) frameworks.push("react-vite");
+	if (files.includes("manage.py")) frameworks.push("django");
+
+	const result = JSON.stringify(
+		{ path, frameworks, fileCount: files.length },
+		null,
+		2,
+	);
+	return { content: [{ type: "text", text: result }] };
+}
+
+async function handleSearchMemory(args: SearchArgs): Promise<ToolCallResult> {
+	const { query, limit = 5 } = args;
+	return {
+		content: [
+			{
+				type: "text",
+				text: JSON.stringify({
+					query,
+					limit,
+					results: [],
+					note: "Memory search requires runtime integration",
+				}),
+			},
+		],
+	};
+}
+
+async function handleListSkills(args: ListSkillsArgs): Promise<ToolCallResult> {
+	const { capability } = args;
+	return {
+		content: [
+			{
+				type: "text",
+				text: JSON.stringify({
+					capability,
+					skills: [],
+					note: "Skill registry requires runtime integration",
+				}),
+			},
+		],
+	};
+}
+
+async function handleInvokeSkill(
+	args: InvokeSkillArgs,
+): Promise<ToolCallResult> {
+	const { name, trigger, context } = args;
+	return {
+		content: [
+			{
+				type: "text",
+				text: JSON.stringify({
+					skill: name,
+					trigger,
+					context,
+					note: "Skill invocation requires runtime integration",
+				}),
+			},
+		],
+	};
+}

package/packages/mcp-adapter/src/types.ts

@@ -0,0 +1,79 @@
+/**
+ * MCP Adapter — Types (RFC-0068)
+ */
+
+// MCP JSON-RPC 2.0 Types
+export interface MCPRequest {
+	jsonrpc: "2.0";
+	id: number | string;
+	method: string;
+	params?: Record<string, unknown>;
+}
+
+export interface MCPResponse {
+	jsonrpc: "2.0";
+	id: number | string;
+	result?: unknown;
+	error?: MCPError;
+}
+
+export interface MCPError {
+	code: number;
+	message: string;
+	data?: unknown;
+}
+
+export interface MCPServerOptions {
+	name?: string;
+	version?: string;
+}
+
+// MCP Protocol 2024-11-05 Capabilities
+export interface ServerCapabilities {
+	tools?: { listChanged?: boolean };
+	resources?: { subscribe?: boolean; listChanged?: boolean };
+	prompts?: { listChanged?: boolean };
+}
+
+export interface InitializeResult {
+	protocolVersion: "2024-11-05";
+	capabilities: ServerCapabilities;
+	serverInfo: { name: string; version: string };
+}
+
+// MCP Tool Definition
+export interface MCPTool {
+	name: string;
+	description: string;
+	inputSchema: Record<string, unknown>;
+}
+
+export interface MCPToolCall {
+	name: string;
+	arguments?: Record<string, unknown>;
+}
+
+export interface ToolCallParams {
+	name: string;
+	arguments?: Record<string, unknown>;
+}
+
+export interface ToolCallResult {
+	content: Array<{ type: "text"; text: string }>;
+	isError?: boolean;
+}
+
+// MCP Resource
+export interface MCPResource {
+	uri: string;
+	name: string;
+	description?: string;
+	mimeType?: string;
+}
+
+// MCP Prompt
+export interface MCPPrompt {
+	name: string;
+	description?: string;
+	arguments?: Array<{ name: string; description?: string; required?: boolean }>;
+}

package/packages/mcp-adapter/test/server.test.ts

@@ -0,0 +1,91 @@
+/**
+ * MCP Adapter Tests (RFC-0068)
+ */
+
+import { describe, it, expect } from "bun:test";
+import { HARNESS_TOOLS, handleToolCall } from "../src/tools.js";
+import type { MCPServerOptions } from "../src/types.js";
+
+describe("MCP Tools", () => {
+	it("exposes 4 harness tools", () => {
+		expect(HARNESS_TOOLS).toHaveLength(4);
+		const names = HARNESS_TOOLS.map((t) => t.name);
+		expect(names).toContain("analyze_workspace");
+		expect(names).toContain("search_memory");
+		expect(names).toContain("list_skills");
+		expect(names).toContain("invoke_skill");
+	});
+
+	it("analyze_workspace tool has correct schema", () => {
+		const tool = HARNESS_TOOLS.find((t) => t.name === "analyze_workspace")!;
+		expect(tool.inputSchema).toBeDefined();
+		const schema = tool.inputSchema as { properties: Record<string, unknown> };
+		expect(schema.properties.path).toBeDefined();
+	});
+
+	it("analyze_workspace returns error for non-existent path", async () => {
+		const result = await handleToolCall("analyze_workspace", {
+			path: "/nonexistent/path/12345",
+		});
+		expect(result.isError).toBe(true);
+		expect(result.content[0].text).toContain("does not exist");
+	});
+
+	it("analyze_workspace detects frameworks in temp dir", async () => {
+		const { mkdirSync, writeFileSync, rmSync } = await import("node:fs");
+		const os = await import("os");
+		const path = await import("node:path");
+		const tmp = os.tmpdir();
+		const testDir = path.join(tmp, "mcp-test-" + Date.now());
+		mkdirSync(testDir);
+		writeFileSync(path.join(testDir, "package.json"), "{}");
+
+		const result = await handleToolCall("analyze_workspace", { path: testDir });
+		rmSync(testDir, { recursive: true });
+
+		expect(result.isError).toBeUndefined();
+		const parsed = JSON.parse(result.content[0].text);
+		expect(parsed.frameworks).toContain("node");
+	});
+
+	it("search_memory returns stub response", async () => {
+		const result = await handleToolCall("search_memory", {
+			query: "frappe",
+			limit: 3,
+		});
+		expect(result.isError).toBeUndefined();
+		const parsed = JSON.parse(result.content[0].text);
+		expect(parsed.note).toContain("runtime integration");
+	});
+
+	it("list_skills returns stub response", async () => {
+		const result = await handleToolCall("list_skills", {});
+		expect(result.isError).toBeUndefined();
+		const parsed = JSON.parse(result.content[0].text);
+		expect(parsed.note).toContain("runtime integration");
+	});
+
+	it("invoke_skill returns stub response", async () => {
+		const result = await handleToolCall("invoke_skill", {
+			name: "test-skill",
+			trigger: { type: "keyword", value: "test" },
+		});
+		expect(result.isError).toBeUndefined();
+		const parsed = JSON.parse(result.content[0].text);
+		expect(parsed.skill).toBe("test-skill");
+	});
+
+	it("unknown tool returns error", async () => {
+		const result = await handleToolCall("unknown_tool");
+		expect(result.isError).toBe(true);
+		expect(result.content[0].text).toContain("Unknown tool");
+	});
+});
+
+describe("MCPServerOptions", () => {
+	it("has correct defaults", () => {
+		const opts: MCPServerOptions = {};
+		expect(opts.name).toBeUndefined();
+		expect(opts.version).toBeUndefined();
+	});
+});

package/packages/mcp-adapter/tsconfig.json

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