@harness-engineering/mcp-server 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Intense Visions, Inc.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/bin/harness-mcp.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/bin/harness-mcp.js

@@ -0,0 +1,6 @@
+#!/usr/bin/env node
+import { startServer } from '../src/index.js';
+startServer().catch((error) => {
+    console.error('Failed to start MCP server:', error);
+    process.exit(1);
+});

package/dist/src/index.d.ts

@@ -0,0 +1,3 @@
+export { createHarnessServer, startServer, getToolDefinitions } from './server.js';
+export { resultToMcpResponse } from './utils/result-adapter.js';
+export { resolveProjectConfig } from './utils/config-resolver.js';

package/dist/src/index.js

@@ -0,0 +1,3 @@
+export { createHarnessServer, startServer, getToolDefinitions } from './server.js';
+export { resultToMcpResponse } from './utils/result-adapter.js';
+export { resolveProjectConfig } from './utils/config-resolver.js';

package/dist/src/resources/learnings.d.ts

@@ -0,0 +1 @@
+export declare function getLearningsResource(projectRoot: string): Promise<string>;

package/dist/src/resources/learnings.js

@@ -0,0 +1,14 @@
+import * as fs from 'fs';
+import * as path from 'path';
+export async function getLearningsResource(projectRoot) {
+    const sections = [];
+    const reviewPath = path.join(projectRoot, '.harness', 'review-learnings.md');
+    if (fs.existsSync(reviewPath)) {
+        sections.push('## Review Learnings\n\n' + fs.readFileSync(reviewPath, 'utf-8'));
+    }
+    const antiPath = path.join(projectRoot, '.harness', 'anti-patterns.md');
+    if (fs.existsSync(antiPath)) {
+        sections.push('## Anti-Pattern Log\n\n' + fs.readFileSync(antiPath, 'utf-8'));
+    }
+    return sections.length > 0 ? sections.join('\n\n---\n\n') : 'No learnings files found.';
+}

package/dist/src/resources/project.d.ts

@@ -0,0 +1 @@
+export declare function getProjectResource(projectRoot: string): Promise<string>;

package/dist/src/resources/project.js

@@ -0,0 +1,9 @@
+import * as fs from 'fs';
+import * as path from 'path';
+export async function getProjectResource(projectRoot) {
+    const agentsPath = path.join(projectRoot, 'AGENTS.md');
+    if (fs.existsSync(agentsPath)) {
+        return fs.readFileSync(agentsPath, 'utf-8');
+    }
+    return '# No AGENTS.md found';
+}

package/dist/src/resources/rules.d.ts

@@ -0,0 +1 @@
+export declare function getRulesResource(projectRoot: string): Promise<string>;

package/dist/src/resources/rules.js

@@ -0,0 +1,36 @@
+import * as fs from 'fs';
+import * as path from 'path';
+export async function getRulesResource(projectRoot) {
+    const rules = [];
+    // Try to read harness config
+    const configPath = path.join(projectRoot, 'harness.config.json');
+    if (fs.existsSync(configPath)) {
+        try {
+            const config = JSON.parse(fs.readFileSync(configPath, 'utf-8'));
+            if (config.layers) {
+                rules.push({ type: 'layer-enforcement', config: config.layers });
+            }
+            if (config.phaseGates) {
+                rules.push({ type: 'phase-gates', config: config.phaseGates });
+            }
+            if (config.rules) {
+                rules.push({ type: 'custom-rules', config: config.rules });
+            }
+        }
+        catch {
+            /* skip malformed config */
+        }
+    }
+    // Try to read .harness/linter.json for linter rules
+    const linterPath = path.join(projectRoot, '.harness', 'linter.json');
+    if (fs.existsSync(linterPath)) {
+        try {
+            const linterConfig = JSON.parse(fs.readFileSync(linterPath, 'utf-8'));
+            rules.push({ type: 'linter', config: linterConfig });
+        }
+        catch {
+            /* skip malformed linter config */
+        }
+    }
+    return JSON.stringify(rules, null, 2);
+}

package/dist/src/resources/skills.d.ts

@@ -0,0 +1 @@
+export declare function getSkillsResource(projectRoot: string): Promise<string>;

package/dist/src/resources/skills.js

@@ -0,0 +1,33 @@
+import * as fs from 'fs';
+import * as path from 'path';
+import * as yaml from 'yaml';
+export async function getSkillsResource(projectRoot) {
+    const skillsDir = path.join(projectRoot, 'agents', 'skills', 'claude-code');
+    const skills = [];
+    if (!fs.existsSync(skillsDir)) {
+        return JSON.stringify(skills, null, 2);
+    }
+    const entries = fs.readdirSync(skillsDir, { withFileTypes: true });
+    for (const entry of entries) {
+        if (!entry.isDirectory())
+            continue;
+        const skillYamlPath = path.join(skillsDir, entry.name, 'skill.yaml');
+        if (!fs.existsSync(skillYamlPath))
+            continue;
+        try {
+            const content = fs.readFileSync(skillYamlPath, 'utf-8');
+            const parsed = yaml.parse(content);
+            skills.push({
+                name: parsed.name,
+                description: parsed.description,
+                cognitive_mode: parsed.cognitive_mode,
+                type: parsed.type,
+                triggers: parsed.triggers,
+            });
+        }
+        catch {
+            /* skip malformed skill files */
+        }
+    }
+    return JSON.stringify(skills, null, 2);
+}

package/dist/src/server.d.ts

@@ -0,0 +1,17 @@
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+type ToolDefinition = {
+    name: string;
+    description: string;
+    inputSchema: Record<string, unknown>;
+};
+declare const RESOURCE_DEFINITIONS: {
+    uri: string;
+    name: string;
+    description: string;
+    mimeType: string;
+}[];
+export declare function getToolDefinitions(): ToolDefinition[];
+export declare function getResourceDefinitions(): typeof RESOURCE_DEFINITIONS;
+export declare function createHarnessServer(projectRoot?: string): Server;
+export declare function startServer(): Promise<void>;
+export {};

package/dist/src/server.js

@@ -0,0 +1,125 @@
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { CallToolRequestSchema, ListToolsRequestSchema, ListResourcesRequestSchema, ReadResourceRequestSchema, } from '@modelcontextprotocol/sdk/types.js';
+import { validateToolDefinition, handleValidateProject } from './tools/validate.js';
+import { checkDependenciesDefinition, handleCheckDependencies } from './tools/architecture.js';
+import { checkDocsDefinition, handleCheckDocs, validateKnowledgeMapDefinition, handleValidateKnowledgeMap, } from './tools/docs.js';
+import { detectEntropyDefinition, handleDetectEntropy, applyFixesDefinition, handleApplyFixes, } from './tools/entropy.js';
+import { generateLinterDefinition, handleGenerateLinter, validateLinterConfigDefinition, handleValidateLinterConfig, } from './tools/linter.js';
+import { initProjectDefinition, handleInitProject } from './tools/init.js';
+import { listPersonasDefinition, handleListPersonas, generatePersonaArtifactsDefinition, handleGeneratePersonaArtifacts, runPersonaDefinition, handleRunPersona, } from './tools/persona.js';
+import { addComponentDefinition, handleAddComponent, runAgentTaskDefinition, handleRunAgentTask, } from './tools/agent.js';
+import { runSkillDefinition, handleRunSkill } from './tools/skill.js';
+import { getSkillsResource } from './resources/skills.js';
+import { getRulesResource } from './resources/rules.js';
+import { getProjectResource } from './resources/project.js';
+import { getLearningsResource } from './resources/learnings.js';
+const TOOL_DEFINITIONS = [
+    validateToolDefinition,
+    checkDependenciesDefinition,
+    checkDocsDefinition,
+    validateKnowledgeMapDefinition,
+    detectEntropyDefinition,
+    applyFixesDefinition,
+    generateLinterDefinition,
+    validateLinterConfigDefinition,
+    initProjectDefinition,
+    listPersonasDefinition,
+    generatePersonaArtifactsDefinition,
+    runPersonaDefinition,
+    addComponentDefinition,
+    runAgentTaskDefinition,
+    runSkillDefinition,
+];
+const TOOL_HANDLERS = {
+    validate_project: handleValidateProject,
+    check_dependencies: handleCheckDependencies,
+    check_docs: handleCheckDocs,
+    validate_knowledge_map: handleValidateKnowledgeMap,
+    detect_entropy: handleDetectEntropy,
+    apply_fixes: handleApplyFixes,
+    generate_linter: handleGenerateLinter,
+    validate_linter_config: handleValidateLinterConfig,
+    init_project: handleInitProject,
+    list_personas: handleListPersonas,
+    generate_persona_artifacts: handleGeneratePersonaArtifacts,
+    run_persona: handleRunPersona,
+    add_component: handleAddComponent,
+    run_agent_task: handleRunAgentTask,
+    run_skill: handleRunSkill,
+};
+const RESOURCE_DEFINITIONS = [
+    {
+        uri: 'harness://skills',
+        name: 'Harness Skills',
+        description: 'Available skills with metadata (name, description, cognitive_mode, type, triggers)',
+        mimeType: 'application/json',
+    },
+    {
+        uri: 'harness://rules',
+        name: 'Harness Rules',
+        description: 'Active linter rules and constraints from harness config',
+        mimeType: 'application/json',
+    },
+    {
+        uri: 'harness://project',
+        name: 'Project Context',
+        description: 'Project structure and agent instructions from AGENTS.md',
+        mimeType: 'text/markdown',
+    },
+    {
+        uri: 'harness://learnings',
+        name: 'Learnings',
+        description: 'Review learnings and anti-pattern log from .harness/',
+        mimeType: 'text/markdown',
+    },
+];
+const RESOURCE_HANDLERS = {
+    'harness://skills': getSkillsResource,
+    'harness://rules': getRulesResource,
+    'harness://project': getProjectResource,
+    'harness://learnings': getLearningsResource,
+};
+export function getToolDefinitions() {
+    return TOOL_DEFINITIONS;
+}
+export function getResourceDefinitions() {
+    return RESOURCE_DEFINITIONS;
+}
+export function createHarnessServer(projectRoot) {
+    const resolvedRoot = projectRoot ?? process.cwd();
+    const server = new Server({ name: 'harness-engineering', version: '0.1.0' }, { capabilities: { tools: {}, resources: {} } });
+    server.setRequestHandler(ListToolsRequestSchema, async () => ({
+        tools: TOOL_DEFINITIONS,
+    }));
+    server.setRequestHandler(CallToolRequestSchema, async (request) => {
+        const { name, arguments: args } = request.params;
+        const handler = TOOL_HANDLERS[name];
+        if (!handler) {
+            return { content: [{ type: 'text', text: `Unknown tool: ${name}` }], isError: true };
+        }
+        return handler(args ?? {});
+    });
+    server.setRequestHandler(ListResourcesRequestSchema, async () => ({
+        resources: RESOURCE_DEFINITIONS,
+    }));
+    server.setRequestHandler(ReadResourceRequestSchema, async (request) => {
+        const uri = request.params.uri;
+        const handler = RESOURCE_HANDLERS[uri];
+        if (!handler) {
+            throw new Error(`Unknown resource: ${uri}`);
+        }
+        const content = await handler(resolvedRoot);
+        const resourceDef = RESOURCE_DEFINITIONS.find((r) => r.uri === uri);
+        const mimeType = resourceDef?.mimeType ?? 'text/plain';
+        return {
+            contents: [{ uri, text: content, mimeType }],
+        };
+    });
+    return server;
+}
+export async function startServer() {
+    const server = createHarnessServer();
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+}

package/dist/src/tools/agent.d.ts

@@ -0,0 +1,79 @@
+export declare const addComponentDefinition: {
+    name: string;
+    description: string;
+    inputSchema: {
+        type: "object";
+        properties: {
+            path: {
+                type: string;
+                description: string;
+            };
+            type: {
+                type: string;
+                enum: string[];
+                description: string;
+            };
+            name: {
+                type: string;
+                description: string;
+            };
+        };
+        required: string[];
+    };
+};
+export declare function handleAddComponent(input: {
+    path: string;
+    type: 'layer' | 'doc' | 'component';
+    name: string;
+}): Promise<{
+    content: {
+        type: "text";
+        text: string;
+    }[];
+    isError: boolean;
+} | {
+    content: {
+        type: "text";
+        text: string;
+    }[];
+    isError?: undefined;
+}>;
+export declare const runAgentTaskDefinition: {
+    name: string;
+    description: string;
+    inputSchema: {
+        type: "object";
+        properties: {
+            task: {
+                type: string;
+                description: string;
+            };
+            path: {
+                type: string;
+                description: string;
+            };
+            timeout: {
+                type: string;
+                description: string;
+            };
+        };
+        required: string[];
+    };
+};
+export declare function handleRunAgentTask(input: {
+    task: string;
+    path?: string;
+    timeout?: number;
+}): Promise<{
+    content: {
+        type: "text";
+        text: string;
+    }[];
+    isError?: undefined;
+} | {
+    content: {
+        type: "text";
+        text: string;
+    }[];
+    isError: boolean;
+}>;

package/dist/src/tools/agent.js

@@ -0,0 +1,96 @@
+import * as path from 'path';
+export const addComponentDefinition = {
+    name: 'add_component',
+    description: 'Add a component (layer, doc, or component type) to the project using the harness CLI',
+    inputSchema: {
+        type: 'object',
+        properties: {
+            path: { type: 'string', description: 'Path to project root directory' },
+            type: {
+                type: 'string',
+                enum: ['layer', 'doc', 'component'],
+                description: 'Type of component to add',
+            },
+            name: { type: 'string', description: 'Name of the component to add' },
+        },
+        required: ['path', 'type', 'name'],
+    },
+};
+export async function handleAddComponent(input) {
+    const projectPath = path.resolve(input.path);
+    const ALLOWED_TYPES = new Set(['layer', 'doc', 'component']);
+    if (!ALLOWED_TYPES.has(input.type)) {
+        return {
+            content: [
+                {
+                    type: 'text',
+                    text: JSON.stringify({ error: `Invalid component type: ${input.type}` }),
+                },
+            ],
+            isError: true,
+        };
+    }
+    try {
+        const { execFileSync } = await import('node:child_process');
+        const output = execFileSync('npx', ['harness', 'add', input.type, input.name], {
+            cwd: projectPath,
+            stdio: 'pipe',
+        });
+        return {
+            content: [{ type: 'text', text: output.toString() }],
+        };
+    }
+    catch (error) {
+        return {
+            content: [
+                {
+                    type: 'text',
+                    text: JSON.stringify({
+                        error: `add_component failed: ${error instanceof Error ? error.message : String(error)}`,
+                    }),
+                },
+            ],
+            isError: true,
+        };
+    }
+}
+export const runAgentTaskDefinition = {
+    name: 'run_agent_task',
+    description: 'Run an agent task using the harness CLI',
+    inputSchema: {
+        type: 'object',
+        properties: {
+            task: { type: 'string', description: 'Task to run' },
+            path: { type: 'string', description: 'Path to project root directory' },
+            timeout: { type: 'number', description: 'Timeout in milliseconds' },
+        },
+        required: ['task'],
+    },
+};
+export async function handleRunAgentTask(input) {
+    const projectPath = input.path ? path.resolve(input.path) : process.cwd();
+    try {
+        const { execFileSync } = await import('node:child_process');
+        const output = execFileSync('npx', ['harness', 'agent', 'run', input.task], {
+            cwd: projectPath,
+            stdio: 'pipe',
+            timeout: input.timeout,
+        });
+        return {
+            content: [{ type: 'text', text: output.toString() }],
+        };
+    }
+    catch (error) {
+        return {
+            content: [
+                {
+                    type: 'text',
+                    text: JSON.stringify({
+                        error: `run_agent_task failed: ${error instanceof Error ? error.message : String(error)}`,
+                    }),
+                },
+            ],
+            isError: true,
+        };
+    }
+}

package/dist/src/tools/architecture.d.ts

@@ -0,0 +1,17 @@
+export declare const checkDependenciesDefinition: {
+    name: string;
+    description: string;
+    inputSchema: {
+        type: "object";
+        properties: {
+            path: {
+                type: string;
+                description: string;
+            };
+        };
+        required: string[];
+    };
+};
+export declare function handleCheckDependencies(input: {
+    path: string;
+}): Promise<import("../utils/result-adapter.js").McpToolResponse>;

package/dist/src/tools/architecture.js

@@ -0,0 +1,45 @@
+import * as path from 'path';
+import { resultToMcpResponse } from '../utils/result-adapter.js';
+import { resolveProjectConfig } from '../utils/config-resolver.js';
+export const checkDependenciesDefinition = {
+    name: 'check_dependencies',
+    description: 'Validate layer boundaries and detect circular dependencies',
+    inputSchema: {
+        type: 'object',
+        properties: {
+            path: { type: 'string', description: 'Path to project root' },
+        },
+        required: ['path'],
+    },
+};
+export async function handleCheckDependencies(input) {
+    const projectPath = path.resolve(input.path);
+    const configResult = resolveProjectConfig(projectPath);
+    if (!configResult.ok)
+        return resultToMcpResponse(configResult);
+    // Delegate to core library
+    try {
+        const { validateDependencies, TypeScriptParser } = await import('@harness-engineering/core');
+        const config = configResult.value;
+        const rawLayers = config.layers ?? [];
+        const layers = rawLayers.map((l) => ({
+            name: l.name,
+            patterns: [l.pattern],
+            allowedDependencies: l.allowedDependencies,
+        }));
+        const parser = new TypeScriptParser();
+        const result = await validateDependencies({ layers, rootDir: projectPath, parser });
+        return resultToMcpResponse(result);
+    }
+    catch (error) {
+        return {
+            content: [
+                {
+                    type: 'text',
+                    text: `Error: ${error instanceof Error ? error.message : String(error)}`,
+                },
+            ],
+            isError: true,
+        };
+    }
+}

package/dist/src/tools/docs.d.ts

@@ -0,0 +1,39 @@
+export declare const checkDocsDefinition: {
+    name: string;
+    description: string;
+    inputSchema: {
+        type: "object";
+        properties: {
+            path: {
+                type: string;
+                description: string;
+            };
+            domain: {
+                type: string;
+                description: string;
+            };
+        };
+        required: string[];
+    };
+};
+export declare function handleCheckDocs(input: {
+    path: string;
+    domain?: string;
+}): Promise<import("../utils/result-adapter.js").McpToolResponse>;
+export declare const validateKnowledgeMapDefinition: {
+    name: string;
+    description: string;
+    inputSchema: {
+        type: "object";
+        properties: {
+            path: {
+                type: string;
+                description: string;
+            };
+        };
+        required: string[];
+    };
+};
+export declare function handleValidateKnowledgeMap(input: {
+    path: string;
+}): Promise<import("../utils/result-adapter.js").McpToolResponse>;

package/dist/src/tools/docs.js

@@ -0,0 +1,65 @@
+import * as path from 'path';
+import { resultToMcpResponse } from '../utils/result-adapter.js';
+export const checkDocsDefinition = {
+    name: 'check_docs',
+    description: 'Analyze documentation coverage',
+    inputSchema: {
+        type: 'object',
+        properties: {
+            path: { type: 'string', description: 'Path to project root' },
+            domain: { type: 'string', description: 'Domain/module to check' },
+        },
+        required: ['path'],
+    },
+};
+export async function handleCheckDocs(input) {
+    try {
+        const { checkDocCoverage } = await import('@harness-engineering/core');
+        const domain = input.domain ?? 'src';
+        const result = await checkDocCoverage(domain, {
+            sourceDir: path.resolve(input.path, 'src'),
+            docsDir: path.resolve(input.path, 'docs'),
+        });
+        return resultToMcpResponse(result);
+    }
+    catch (error) {
+        return {
+            content: [
+                {
+                    type: 'text',
+                    text: `Error: ${error instanceof Error ? error.message : String(error)}`,
+                },
+            ],
+            isError: true,
+        };
+    }
+}
+export const validateKnowledgeMapDefinition = {
+    name: 'validate_knowledge_map',
+    description: 'Validate AGENTS.md knowledge map structure and links',
+    inputSchema: {
+        type: 'object',
+        properties: {
+            path: { type: 'string', description: 'Path to project root' },
+        },
+        required: ['path'],
+    },
+};
+export async function handleValidateKnowledgeMap(input) {
+    try {
+        const { validateKnowledgeMap } = await import('@harness-engineering/core');
+        const result = await validateKnowledgeMap(path.resolve(input.path));
+        return resultToMcpResponse(result);
+    }
+    catch (error) {
+        return {
+            content: [
+                {
+                    type: 'text',
+                    text: `Error: ${error instanceof Error ? error.message : String(error)}`,
+                },
+            ],
+            isError: true,
+        };
+    }
+}