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

package/mcp-server/QUICKSTART.md

@@ -0,0 +1,172 @@
+# MCP Server Quick Start
+
+This guide helps you set up the Software Methodology MCP server for use with Claude Desktop.
+
+## Prerequisites
+
+- Node.js 14 or higher
+- Claude Desktop app installed
+
+## Installation
+
+You can install the software-methodology MCP server in two ways:
+
+### Option 1: Install via npm (Recommended)
+
+```bash
+# Install the parent package which includes the MCP server
+npm install @schilling.mark.a/software-methodology
+
+# Navigate to the MCP server directory
+cd node_modules/@schilling.mark.a/software-methodology/mcp-server
+
+# Install dependencies and build
+npm install
+npm run build
+```
+
+### Option 2: Clone from Source
+
+```bash
+# Clone the repository
+git clone https://github.com/MarkSchilling/software-methodology.git
+cd software-methodology/mcp-server
+
+# Install dependencies
+npm install
+
+# Build the server
+npm run build
+```
+
+## Configuration
+
+## Configuration
+
+### 1. Configure Claude Desktop
+
+Edit your Claude Desktop configuration file:
+
+**macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`  
+**Windows:** `%APPDATA%\Claude\claude_desktop_config.json`  
+**Linux:** `~/.config/Claude/claude_desktop_config.json`
+
+Add the MCP server configuration (use the path matching your installation method):
+
+**For npm installation:**
+```json
+{
+  "mcpServers": {
+    "software-methodology": {
+      "command": "node",
+      "args": [
+        "/FULL/PATH/TO/node_modules/@schilling.mark.a/software-methodology/mcp-server/dist/index.js"
+      ]
+    }
+  }
+}
+```
+
+**For source installation:**
+```json
+{
+  "mcpServers": {
+    "software-methodology": {
+      "command": "node",
+      "args": [
+        "/FULL/PATH/TO/software-methodology/mcp-server/dist/index.js"
+      ]
+    }
+  }
+}
+```
+
+**Important:** Replace `/FULL/PATH/TO/` with the actual absolute path on your system.
+
+### 2. Restart Claude Desktop
+
+Quit Claude Desktop completely and restart it. The MCP server will start automatically.
+
+## Verify Installation
+
+In Claude Desktop, try these prompts:
+
+1. **"List all available skills"**
+   - Should return 11 methodology skills
+
+2. **"Show me the SOLID principles"**
+   - Should return content from clean-code/references/solid.md
+
+3. **"What are the pains for Individual Developer segment?"**
+   - Should return pains from the VPC
+
+4. **"What should I do next?"**
+   - Should analyze project state and suggest next step
+
+5. **"Search for test-first guidance"**
+   - Should return RED-GREEN-REFACTOR content
+
+## Available Tools
+
+The MCP server provides these tools to Claude:
+
+- `read_skill` - Get SKILL.md content for any skill
+- `list_skills` - List all 11 skills with descriptions
+- `read_reference` - Get specific reference documents
+- `list_references` - List references for a skill
+- `query_vpc_segments` - Get customer segments
+- `query_vpc_customer_jobs` - Get jobs for a segment
+- `query_vpc_pains` - Get pains for a segment
+- `query_vpc_gains` - Get gains for a segment
+- `search_vpc` - Search VPC for terms
+- `search_guidance` - Search methodology for relevant content
+- `suggest_next_step` - Get next methodology step
+- `validate_gherkin` - Validate feature files
+
+## Troubleshooting
+
+### Server not starting
+
+1. Check Claude Desktop logs (Help → View Logs)
+2. Verify the path in config is absolute, not relative
+3. Ensure `npm run build` completed successfully
+4. Test the server manually:
+   ```bash
+   cd mcp-server
+   node dist/index.js
+   ```
+
+### Tools not appearing
+
+1. Restart Claude Desktop completely (Quit, not just close window)
+2. Check config JSON syntax is valid (use a JSON validator)
+3. Verify server name matches exactly: `"software-methodology"`
+
+### Permission errors
+
+On macOS/Linux, ensure the script is executable:
+```bash
+chmod +x mcp-server/dist/index.js
+```
+
+## Development Mode
+
+To develop the MCP server with auto-rebuild:
+
+```bash
+cd mcp-server
+npm run watch
+```
+
+Changes to TypeScript will rebuild automatically. Restart Claude Desktop to pick up changes.
+
+## Next Steps
+
+Once the MCP server is running:
+
+1. Try querying the VPC for your project's business context
+2. Ask "what should I do next?" to get methodology guidance
+3. Validate your Gherkin scenarios before implementation
+4. Search for design patterns when refactoring
+
+The MCP server works alongside the existing GitHub Copilot integration - use whichever AI assistant fits your workflow.

package/mcp-server/README.md

@@ -0,0 +1,171 @@
+# Software Methodology MCP Server
+
+Model Context Protocol (MCP) server providing structured access to the software methodology documentation.
+
+## Features
+
+- **Read Skills**: Access SKILL.md documentation for any of the 11 skills
+- **Read References**: Get specific reference documents (e.g., SOLID principles, design patterns)
+- **Query VPC**: Extract customer segments, jobs, pains, and gains from Value Proposition Canvas
+- **Search Guidance**: Find relevant methodology content by scenario or keyword
+- **Suggest Next Steps**: Get methodology guidance based on current project state
+- **Validate Gherkin**: Check feature files against BDD best practices
+
+## Installation
+
+**Via npm (recommended):**
+```bash
+npm install @schilling.mark.a/software-methodology
+cd node_modules/@schilling.mark.a/software-methodology/mcp-server
+npm install
+npm run build
+```
+
+**From source:**
+```bash
+git clone https://github.com/MarkSchilling/software-methodology.git
+cd software-methodology/mcp-server
+npm install
+npm run build
+```
+
+See [QUICKSTART.md](QUICKSTART.md) for detailed setup instructions.
+
+## Usage with Claude Desktop
+
+Add to your Claude Desktop config (`~/Library/Application Support/Claude/claude_desktop_config.json`):
+
+**For npm installation:**
+```json
+{
+  "mcpServers": {
+    "software-methodology": {
+      "command": "node",
+      "args": [
+        "/path/to/node_modules/@schilling.mark.a/software-methodology/mcp-server/dist/index.js"
+      ]
+    }
+  }
+}
+```
+
+**For source installation:**
+```json
+{
+  "mcpServers": {
+    "software-methodology": {
+      "command": "node",
+      "args": [
+        "/path/to/software-methodology/mcp-server/dist/index.js"
+      ]
+    }
+  }
+}
+```
+
+## Available Tools
+
+### read_skill
+Read main SKILL.md documentation for a specific skill.
+
+```
+Input: { skill_name: "atdd-workflow" }
+```
+
+### list_skills
+List all 11 available skills with descriptions.
+
+### read_reference
+Read a specific reference document.
+
+```
+Input: { reference_path: "clean-code/solid.md" }
+```
+
+### list_references
+List all reference documents for a skill.
+
+```
+Input: { skill_name: "clean-code" }
+```
+
+### query_vpc_segments
+Get all customer segments from the Value Proposition Canvas.
+
+### query_vpc_customer_jobs
+Get customer jobs for a specific segment.
+
+```
+Input: { segment: "Individual Developer" }
+```
+
+### query_vpc_pains
+Get pains for a specific segment.
+
+```
+Input: { segment: "Individual Developer" }
+```
+
+### query_vpc_gains
+Get gains for a specific segment.
+
+```
+Input: { segment: "Individual Developer" }
+```
+
+### search_vpc
+Search for specific terms across VPC pains and gains.
+
+```
+Input: { query: "tests" }
+```
+
+### search_guidance
+Search across all skills and references for relevant guidance.
+
+```
+Input: { query: "test before code" }
+```
+
+### suggest_next_step
+Get suggestion for next methodology step based on current project state.
+
+```
+Input: { project_path: "/optional/path/to/project" }
+```
+
+### validate_gherkin
+Validate a Gherkin feature file against methodology best practices.
+
+```
+Input: { content: "Feature: ...\n  As a...\n  ..." }
+```
+
+## Development
+
+```bash
+# Watch mode during development
+npm run watch
+
+# Run tests
+npm test
+
+# Run tests in watch mode
+npm run test:watch
+```
+
+## Architecture
+
+- **index.ts**: MCP server setup and request handlers
+- **repository.ts**: File system access and content parsing
+- **tools/**: Individual tool implementations
+  - skill-reader.ts
+  - reference-reader.ts
+  - vpc-querier.ts
+  - guidance-searcher.ts
+  - next-step-suggester.ts
+  - gherkin-validator.ts
+
+## License
+
+MIT

package/mcp-server/dist/index.d.ts

@@ -0,0 +1,12 @@
+#!/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
+ */
+export {};

package/mcp-server/dist/index.js

@@ -0,0 +1,296 @@
+#!/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);
+            case "list_skills":
+                return await skillReader.listSkills();
+            case "read_reference":
+                return await referenceReader.readReference(args?.reference_path);
+            case "list_references":
+                return await referenceReader.listReferences(args?.skill_name);
+            case "query_vpc_segments":
+                return await vpcQuerier.getSegments();
+            case "query_vpc_customer_jobs":
+                return await vpcQuerier.getCustomerJobs(args?.segment);
+            case "query_vpc_pains":
+                return await vpcQuerier.getPains(args?.segment);
+            case "query_vpc_gains":
+                return await vpcQuerier.getGains(args?.segment);
+            case "search_vpc":
+                return await vpcQuerier.search(args?.query);
+            case "search_guidance":
+                return await guidanceSearcher.search(args?.query);
+            case "suggest_next_step":
+                return await nextStepSuggester.suggest(args?.project_path);
+            case "validate_gherkin":
+                return await gherkinValidator.validate(args?.content);
+            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);
+});

package/mcp-server/dist/repository.d.ts

@@ -0,0 +1,59 @@
+export interface Skill {
+    name: string;
+    displayName: string;
+    description: string;
+    path: string;
+}
+export interface Reference {
+    name: string;
+    path: string;
+    skill: string;
+}
+/**
+ * Repository for accessing methodology files
+ */
+export declare class MethodologyRepository {
+    private methodologyRoot;
+    constructor();
+    /**
+     * List all available skills
+     */
+    listSkills(): Promise<Skill[]>;
+    /**
+     * Read a skill's main documentation
+     */
+    readSkill(skillName: string): Promise<string>;
+    /**
+     * List references for a skill
+     */
+    listReferences(skillName: string): Promise<Reference[]>;
+    /**
+     * Read a reference document
+     */
+    readReference(skillName: string, referenceName: string): Promise<string>;
+    /**
+     * Read VPC content
+     */
+    readVPC(): Promise<string>;
+    /**
+     * Read story map backbone
+     */
+    readStoryMap(): Promise<string | null>;
+    /**
+     * List feature files
+     */
+    listFeatureFiles(projectPath?: string): Promise<string[]>;
+    /**
+     * Search all content
+     */
+    searchContent(query: string): Promise<Array<{
+        file: string;
+        content: string;
+        relevance: number;
+    }>>;
+    private walkDirectory;
+    private extractDescription;
+    private toDisplayName;
+    private calculateRelevance;
+    private extractRelevantSection;
+}