@schilling.mark.a/software-methodology 1.0.0 → 1.0.1

package/mcp-server/dist/tools/reference-reader.js

@@ -0,0 +1,57 @@
+export class ReferenceReader {
+    repository;
+    constructor(repository) {
+        this.repository = repository;
+    }
+    async readReference(referencePath) {
+        // Parse path like "clean-code/solid.md"
+        const parts = referencePath.split("/");
+        if (parts.length !== 2) {
+            throw new Error("Reference path must be in format 'skill-name/reference-name.md'");
+        }
+        const [skillName, referenceName] = parts;
+        try {
+            const content = await this.repository.readReference(skillName, referenceName);
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: content,
+                    },
+                ],
+            };
+        }
+        catch (error) {
+            const references = await this.repository.listReferences(skillName);
+            if (references.length === 0) {
+                throw new Error(`Skill '${skillName}' has no reference documents or doesn't exist`);
+            }
+            const availableRefs = references.map((r) => r.name).join(", ");
+            throw new Error(`Reference '${referenceName}' not found in skill '${skillName}'. Available references: ${availableRefs}`);
+        }
+    }
+    async listReferences(skillName) {
+        const references = await this.repository.listReferences(skillName);
+        if (references.length === 0) {
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: `Skill '${skillName}' has no reference documents.`,
+                    },
+                ],
+            };
+        }
+        const text = references
+            .map((ref) => `- ${ref.name}`)
+            .join("\n");
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: `# References for ${skillName} (${references.length})\n\n${text}`,
+                },
+            ],
+        };
+    }
+}

package/mcp-server/dist/tools/skill-reader.d.ts

@@ -0,0 +1,17 @@
+import { MethodologyRepository } from "../repository.js";
+export declare class SkillReader {
+    private repository;
+    constructor(repository: MethodologyRepository);
+    readSkill(skillName: string): Promise<{
+        content: {
+            type: "text";
+            text: string;
+        }[];
+    }>;
+    listSkills(): Promise<{
+        content: {
+            type: "text";
+            text: string;
+        }[];
+    }>;
+}

package/mcp-server/dist/tools/skill-reader.js

@@ -0,0 +1,38 @@
+export class SkillReader {
+    repository;
+    constructor(repository) {
+        this.repository = repository;
+    }
+    async readSkill(skillName) {
+        try {
+            const content = await this.repository.readSkill(skillName);
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: content,
+                    },
+                ],
+            };
+        }
+        catch (error) {
+            const skills = await this.repository.listSkills();
+            const availableSkills = skills.map((s) => s.name).join(", ");
+            throw new Error(`Skill '${skillName}' not found. Available skills: ${availableSkills}`);
+        }
+    }
+    async listSkills() {
+        const skills = await this.repository.listSkills();
+        const text = skills
+            .map((skill) => `**${skill.displayName}** (${skill.name}):\n  ${skill.description}`)
+            .join("\n\n");
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: `# Available Skills (${skills.length})\n\n${text}`,
+                },
+            ],
+        };
+    }
+}

package/mcp-server/dist/tools/vpc-querier.d.ts

@@ -0,0 +1,37 @@
+import { MethodologyRepository } from "../repository.js";
+export declare class VPCQuerier {
+    private repository;
+    constructor(repository: MethodologyRepository);
+    getSegments(): Promise<{
+        content: {
+            type: "text";
+            text: string;
+        }[];
+    }>;
+    getCustomerJobs(segmentName: string): Promise<{
+        content: {
+            type: "text";
+            text: string;
+        }[];
+    }>;
+    getPains(segmentName: string): Promise<{
+        content: {
+            type: "text";
+            text: string;
+        }[];
+    }>;
+    getGains(segmentName: string): Promise<{
+        content: {
+            type: "text";
+            text: string;
+        }[];
+    }>;
+    search(query: string): Promise<{
+        content: {
+            type: "text";
+            text: string;
+        }[];
+    }>;
+    private parseSegments;
+    private extractList;
+}

package/mcp-server/dist/tools/vpc-querier.js

@@ -0,0 +1,158 @@
+export class VPCQuerier {
+    repository;
+    constructor(repository) {
+        this.repository = repository;
+    }
+    async getSegments() {
+        const vpc = await this.repository.readVPC();
+        const segments = this.parseSegments(vpc);
+        const text = segments.map((s) => `- ${s.name}`).join("\n");
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: `# Customer Segments (${segments.length})\n\n${text}`,
+                },
+            ],
+        };
+    }
+    async getCustomerJobs(segmentName) {
+        const vpc = await this.repository.readVPC();
+        const segments = this.parseSegments(vpc);
+        const segment = segments.find((s) => s.name === segmentName);
+        if (!segment) {
+            const available = segments.map((s) => s.name).join(", ");
+            throw new Error(`Segment '${segmentName}' not found. Available segments: ${available}`);
+        }
+        const text = segment.customerJobs
+            .map((job, i) => `${i + 1}. ${job}`)
+            .join("\n");
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: `# Customer Jobs for ${segmentName}\n\n${text}`,
+                },
+            ],
+        };
+    }
+    async getPains(segmentName) {
+        const vpc = await this.repository.readVPC();
+        const segments = this.parseSegments(vpc);
+        const segment = segments.find((s) => s.name === segmentName);
+        if (!segment) {
+            const available = segments.map((s) => s.name).join(", ");
+            throw new Error(`Segment '${segmentName}' not found. Available segments: ${available}`);
+        }
+        const text = segment.pains
+            .map((pain, i) => `${i + 1}. ${pain}`)
+            .join("\n");
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: `# Pains for ${segmentName}\n\n${text}`,
+                },
+            ],
+        };
+    }
+    async getGains(segmentName) {
+        const vpc = await this.repository.readVPC();
+        const segments = this.parseSegments(vpc);
+        const segment = segments.find((s) => s.name === segmentName);
+        if (!segment) {
+            const available = segments.map((s) => s.name).join(", ");
+            throw new Error(`Segment '${segmentName}' not found. Available segments: ${available}`);
+        }
+        const text = segment.gains
+            .map((gain, i) => `${i + 1}. ${gain}`)
+            .join("\n");
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: `# Gains for ${segmentName}\n\n${text}`,
+                },
+            ],
+        };
+    }
+    async search(query) {
+        const vpc = await this.repository.readVPC();
+        const segments = this.parseSegments(vpc);
+        const results = [];
+        const queryLower = query.toLowerCase();
+        for (const segment of segments) {
+            for (const pain of segment.pains) {
+                if (pain.toLowerCase().includes(queryLower)) {
+                    results.push({ segment: segment.name, type: "pain", text: pain });
+                }
+            }
+            for (const gain of segment.gains) {
+                if (gain.toLowerCase().includes(queryLower)) {
+                    results.push({ segment: segment.name, type: "gain", text: gain });
+                }
+            }
+        }
+        if (results.length === 0) {
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: `No results found for '${query}' in Value Proposition Canvas.`,
+                    },
+                ],
+            };
+        }
+        const text = results
+            .map((r) => `**[${r.segment}] ${r.type.toUpperCase()}:** ${r.text}`)
+            .join("\n\n");
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: `# VPC Search Results for '${query}'\n\n${text}`,
+                },
+            ],
+        };
+    }
+    parseSegments(vpcContent) {
+        const segments = [];
+        const segmentRegex = /## Segment: (.+?)\n/g;
+        let match;
+        const segmentStarts = [];
+        while ((match = segmentRegex.exec(vpcContent)) !== null) {
+            segmentStarts.push({ name: match[1], index: match.index });
+        }
+        for (let i = 0; i < segmentStarts.length; i++) {
+            const start = segmentStarts[i];
+            const end = i + 1 < segmentStarts.length ? segmentStarts[i + 1].index : vpcContent.length;
+            const segmentContent = vpcContent.slice(start.index, end);
+            segments.push({
+                name: start.name,
+                customerJobs: this.extractList(segmentContent, "#### Customer Jobs"),
+                pains: this.extractList(segmentContent, "#### Pains"),
+                gains: this.extractList(segmentContent, "#### Gains"),
+            });
+        }
+        return segments;
+    }
+    extractList(content, heading) {
+        const headingIndex = content.indexOf(heading);
+        if (headingIndex === -1)
+            return [];
+        const afterHeading = content.slice(headingIndex + heading.length);
+        const nextHeadingIndex = afterHeading.search(/####|###|##/);
+        const section = nextHeadingIndex === -1
+            ? afterHeading
+            : afterHeading.slice(0, nextHeadingIndex);
+        const lines = section.split("\n");
+        const items = [];
+        for (const line of lines) {
+            const match = line.match(/^\d+\.\s+\*\*(.+?)\*\*\s*—\s*(.+)/);
+            if (match) {
+                items.push(`${match[1]} — ${match[2]}`);
+            }
+        }
+        return items;
+    }
+}

package/mcp-server/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "@schilling.mark.a/software-methodology-mcp",
+  "version": "0.1.1",
+  "type": "module",
+  "description": "MCP server providing structured access to software methodology skills, references, and guidance",
+  "bin": {
+    "software-methodology-mcp": "./dist/index.js"
+  },
+  "scripts": {
+    "build": "tsc",
+    "watch": "tsc --watch",
+    "prepare": "npm run build",
+    "test": "jest",
+    "test:watch": "jest --watch"
+  },
+  "keywords": [
+    "mcp",
+    "mcp-server",
+    "methodology",
+    "software-development",
+    "bdd",
+    "atdd",
+    "clean-code"
+  ],
+  "author": "Mark Schilling",
+  "license": "MIT",
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^0.5.0"
+  },
+  "devDependencies": {
+    "@types/node": "^20.11.0",
+    "typescript": "^5.3.3",
+    "jest": "^29.7.0",
+    "@types/jest": "^29.5.11"
+  },
+  "files": [
+    "dist/",
+    "../docs/**/*.md",
+    "../**/SKILL.md",
+    "../**/references/**/*.md"
+  ]
+}

package/mcp-server/src/index.ts

@@ -0,0 +1,331 @@
+#!/usr/bin/env node
+
+/**
+ * Software Methodology MCP Server
+ * 
+ * Provides structured access to software methodology documentation:
+ * - 11 skills (product-strategy through continuous-improvement)
+ * - Reference documents for each skill
+ * - Value Proposition Canvas queries
+ * - Guidance search across all content
+ * - Next-step suggestions based on current context
+ */
+
+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 { MethodologyRepository } from "./repository.js";
+import { SkillReader } from "./tools/skill-reader.js";
+import { ReferenceReader } from "./tools/reference-reader.js";
+import { VPCQuerier } from "./tools/vpc-querier.js";
+import { GuidanceSearcher } from "./tools/guidance-searcher.js";
+import { NextStepSuggester } from "./tools/next-step-suggester.js";
+import { GherkinValidator } from "./tools/gherkin-validator.js";
+
+const server = new Server(
+  {
+    name: "software-methodology",
+    version: "0.1.0",
+  },
+  {
+    capabilities: {
+      tools: {},
+      resources: {},
+    },
+  }
+);
+
+// Initialize repository
+const repository = new MethodologyRepository();
+
+// Initialize tools
+const skillReader = new SkillReader(repository);
+const referenceReader = new ReferenceReader(repository);
+const vpcQuerier = new VPCQuerier(repository);
+const guidanceSearcher = new GuidanceSearcher(repository);
+const nextStepSuggester = new NextStepSuggester(repository);
+const gherkinValidator = new GherkinValidator(repository);
+
+/**
+ * List all available tools
+ */
+server.setRequestHandler(ListToolsRequestSchema, async () => {
+  return {
+    tools: [
+      {
+        name: "read_skill",
+        description: "Read main SKILL.md documentation for a specific skill",
+        inputSchema: {
+          type: "object",
+          properties: {
+            skill_name: {
+              type: "string",
+              description: "Name of the skill (e.g., 'atdd-workflow', 'clean-code', 'product-strategy')",
+            },
+          },
+          required: ["skill_name"],
+        },
+      },
+      {
+        name: "list_skills",
+        description: "List all available skills in the methodology",
+        inputSchema: {
+          type: "object",
+          properties: {},
+        },
+      },
+      {
+        name: "read_reference",
+        description: "Read a specific reference document from a skill",
+        inputSchema: {
+          type: "object",
+          properties: {
+            reference_path: {
+              type: "string",
+              description: "Path to reference (e.g., 'clean-code/solid.md', 'atdd-workflow/red-phase.md')",
+            },
+          },
+          required: ["reference_path"],
+        },
+      },
+      {
+        name: "list_references",
+        description: "List all reference documents for a specific skill",
+        inputSchema: {
+          type: "object",
+          properties: {
+            skill_name: {
+              type: "string",
+              description: "Name of the skill",
+            },
+          },
+          required: ["skill_name"],
+        },
+      },
+      {
+        name: "query_vpc_segments",
+        description: "Get all customer segments from Value Proposition Canvas",
+        inputSchema: {
+          type: "object",
+          properties: {},
+        },
+      },
+      {
+        name: "query_vpc_customer_jobs",
+        description: "Get customer jobs for a specific segment",
+        inputSchema: {
+          type: "object",
+          properties: {
+            segment: {
+              type: "string",
+              description: "Customer segment name (e.g., 'Individual Developer')",
+            },
+          },
+          required: ["segment"],
+        },
+      },
+      {
+        name: "query_vpc_pains",
+        description: "Get pains for a specific segment",
+        inputSchema: {
+          type: "object",
+          properties: {
+            segment: {
+              type: "string",
+              description: "Customer segment name",
+            },
+          },
+          required: ["segment"],
+        },
+      },
+      {
+        name: "query_vpc_gains",
+        description: "Get gains for a specific segment",
+        inputSchema: {
+          type: "object",
+          properties: {
+            segment: {
+              type: "string",
+              description: "Customer segment name",
+            },
+          },
+          required: ["segment"],
+        },
+      },
+      {
+        name: "search_vpc",
+        description: "Search for specific terms across VPC pains and gains",
+        inputSchema: {
+          type: "object",
+          properties: {
+            query: {
+              type: "string",
+              description: "Search term",
+            },
+          },
+          required: ["query"],
+        },
+      },
+      {
+        name: "search_guidance",
+        description: "Search across all skills and references for relevant guidance",
+        inputSchema: {
+          type: "object",
+          properties: {
+            query: {
+              type: "string",
+              description: "What you're looking for (e.g., 'test before code', 'many parameters', 'hard to test')",
+            },
+          },
+          required: ["query"],
+        },
+      },
+      {
+        name: "suggest_next_step",
+        description: "Get suggestion for next methodology step based on current project state",
+        inputSchema: {
+          type: "object",
+          properties: {
+            project_path: {
+              type: "string",
+              description: "Path to project directory (optional, defaults to current directory)",
+            },
+          },
+        },
+      },
+      {
+        name: "validate_gherkin",
+        description: "Validate a Gherkin feature file against methodology best practices",
+        inputSchema: {
+          type: "object",
+          properties: {
+            content: {
+              type: "string",
+              description: "Gherkin feature file content to validate",
+            },
+          },
+          required: ["content"],
+        },
+      },
+    ],
+  };
+});
+
+/**
+ * Handle tool execution
+ */
+server.setRequestHandler(CallToolRequestSchema, async (request) => {
+  const { name, arguments: args } = request.params;
+
+  try {
+    switch (name) {
+      case "read_skill":
+        return await skillReader.readSkill(args?.skill_name as string);
+      
+      case "list_skills":
+        return await skillReader.listSkills();
+      
+      case "read_reference":
+        return await referenceReader.readReference(args?.reference_path as string);
+      
+      case "list_references":
+        return await referenceReader.listReferences(args?.skill_name as string);
+      
+      case "query_vpc_segments":
+        return await vpcQuerier.getSegments();
+      
+      case "query_vpc_customer_jobs":
+        return await vpcQuerier.getCustomerJobs(args?.segment as string);
+      
+      case "query_vpc_pains":
+        return await vpcQuerier.getPains(args?.segment as string);
+      
+      case "query_vpc_gains":
+        return await vpcQuerier.getGains(args?.segment as string);
+      
+      case "search_vpc":
+        return await vpcQuerier.search(args?.query as string);
+      
+      case "search_guidance":
+        return await guidanceSearcher.search(args?.query as string);
+      
+      case "suggest_next_step":
+        return await nextStepSuggester.suggest(args?.project_path as string | undefined);
+      
+      case "validate_gherkin":
+        return await gherkinValidator.validate(args?.content as string);
+      
+      default:
+        throw new Error(`Unknown tool: ${name}`);
+    }
+  } catch (error) {
+    return {
+      content: [
+        {
+          type: "text",
+          text: `Error: ${error instanceof Error ? error.message : String(error)}`,
+        },
+      ],
+      isError: true,
+    };
+  }
+});
+
+/**
+ * List resources (alternative access pattern to tools)
+ */
+server.setRequestHandler(ListResourcesRequestSchema, async () => {
+  const skills = await repository.listSkills();
+  
+  return {
+    resources: skills.map((skill) => ({
+      uri: `methodology://skill/${skill.name}`,
+      mimeType: "text/markdown",
+      name: skill.displayName,
+      description: skill.description,
+    })),
+  };
+});
+
+/**
+ * Read resource
+ */
+server.setRequestHandler(ReadResourceRequestSchema, async (request) => {
+  const uri = request.params.uri;
+  
+  if (uri.startsWith("methodology://skill/")) {
+    const skillName = uri.replace("methodology://skill/", "");
+    const result = await skillReader.readSkill(skillName);
+    
+    return {
+      contents: [
+        {
+          uri,
+          mimeType: "text/markdown",
+          text: result.content[0].text,
+        },
+      ],
+    };
+  }
+  
+  throw new Error(`Unknown resource URI: ${uri}`);
+});
+
+/**
+ * Start the server
+ */
+async function main() {
+  const transport = new StdioServerTransport();
+  await server.connect(transport);
+  console.error("Software Methodology MCP server running on stdio");
+}
+
+main().catch((error) => {
+  console.error("Fatal error in main():", error);
+  process.exit(1);
+});