mcp-ai-agent-guidelines 0.7.2 → 0.7.3

package/README.md

@@ -137,7 +137,9 @@ After adding the server, open your chat client (e.g., Cline in VS Code). The too
 Example prompts:
 - "Use hierarchical-prompt-builder to create a refactor plan for src/index.ts with outputFormat markdown."
 - "Analyze this Python file with code-hygiene-analyzer; highlight security issues."
-- "Generate a Mermaid diagram for our pipeline using mermaid-diagram-generator (flowchart)."
+- "Generate a Mermaid sequence diagram showing: User sends request to API, API queries Database, Database returns data, API responds to User."
+- "Create an ER diagram for: Customer has Orders, Order contains LineItems, Product referenced in LineItems."
+- "Build a user journey map for our checkout flow using mermaid-diagram-generator."
 
 Tip: Most clients can pass file content automatically when you select a file and invoke a tool.
 
@@ -145,6 +147,135 @@ GitHub Chat (VS Code): In the chat, type your request and pick a tool suggestion
 
 ## Features
 
+> **🆕 NEW: Serena-Inspired Strategies** — We've integrated effective agent strategies from [@oraios/serena](https://github.com/oraios/serena) including semantic code analysis, project onboarding, and flexible mode switching. See [docs/SERENA_STRATEGIES.md](./docs/SERENA_STRATEGIES.md) for details.
+
+> **🌊 NEW: Flow-Based Prompting** — Advanced prompting strategies inspired by [@ruvnet/claude-flow](https://github.com/ruvnet/claude-flow) including prompt chaining, declarative flows, and dynamic orchestration.
+> - **Examples**: [docs/FLOW_PROMPTING_EXAMPLES.md](./docs/FLOW_PROMPTING_EXAMPLES.md)
+> - **Integration Guide**: [docs/FLOW_SERENA_INTEGRATION.md](./docs/FLOW_SERENA_INTEGRATION.md) - Combining flow-based prompting with Serena memory patterns
+
+<details>
+<summary><strong>🔗 Prompt Chaining Builder</strong> — Multi-step prompts with output passing (NEW)</summary>
+
+Usage: `prompt-chaining-builder`
+
+| Parameter      | Required | Description                           |
+| -------------- | -------- | ------------------------------------- |
+| `chainName`    | ✅        | Name of the prompt chain              |
+| `steps`        | ✅        | Array of chain steps with prompts     |
+| `description`  | ❌        | Description of chain purpose          |
+| `context`      | ❌        | Global context for the chain          |
+| `globalVariables` | ❌     | Variables accessible to all steps     |
+| `executionStrategy` | ❌   | sequential/parallel-where-possible    |
+
+Build sophisticated multi-step prompt workflows where each step can depend on outputs from previous steps. Supports error handling strategies (skip/retry/abort) and automatic Mermaid visualization.
+
+**Example:**
+```typescript
+{
+  chainName: "Security Analysis Pipeline",
+  steps: [
+    {
+      name: "Scan",
+      prompt: "Scan for vulnerabilities",
+      outputKey: "vulns"
+    },
+    {
+      name: "Assess",
+      prompt: "Assess severity of {{vulns}}",
+      dependencies: ["vulns"],
+      errorHandling: "retry"
+    }
+  ]
+}
+```
+
+</details>
+
+<details>
+<summary><strong>🌊 Prompt Flow Builder</strong> — Declarative flows with branching/loops (NEW)</summary>
+
+Usage: `prompt-flow-builder`
+
+| Parameter      | Required | Description                           |
+| -------------- | -------- | ------------------------------------- |
+| `flowName`     | ✅        | Name of the prompt flow               |
+| `nodes`        | ✅        | Flow nodes (prompt/condition/loop/parallel/merge/transform) |
+| `edges`        | ❌        | Connections between nodes with conditions |
+| `entryPoint`   | ❌        | Starting node ID                      |
+| `variables`    | ❌        | Flow-level variables                  |
+| `outputFormat` | ❌        | markdown/mermaid/both                 |
+
+Create complex adaptive prompt flows with conditional branching, loops, parallel execution, and merge points. Automatically generates Mermaid flowcharts and execution guides.
+
+**Example:**
+```typescript
+{
+  flowName: "Adaptive Code Review",
+  nodes: [
+    { id: "analyze", type: "prompt", name: "Analyze" },
+    { id: "check", type: "condition", name: "Complex?",
+      config: { expression: "complexity > 10" } },
+    { id: "deep", type: "prompt", name: "Deep Review" },
+    { id: "quick", type: "prompt", name: "Quick Check" }
+  ],
+  edges: [
+    { from: "analyze", to: "check" },
+    { from: "check", to: "deep", condition: "true" },
+    { from: "check", to: "quick", condition: "false" }
+  ]
+}
+```
+
+</details>
+
+<details>
+<summary><strong>🔍 Semantic Code Analyzer</strong> — Symbol-based code understanding (NEW)</summary>
+
+Usage: `semantic-code-analyzer`
+
+| Parameter      | Required | Description                           |
+| -------------- | -------- | ------------------------------------- |
+| `codeContent`  | ✅        | Code content to analyze               |
+| `language`     | ❌        | Programming language (auto-detected)  |
+| `analysisType` | ❌        | symbols/structure/dependencies/patterns/all |
+
+Performs semantic analysis to identify symbols, dependencies, patterns, and structure. Inspired by Serena's language server approach.
+
+</details>
+
+<details>
+<summary><strong>🚀 Project Onboarding</strong> — Comprehensive project familiarization (NEW)</summary>
+
+Usage: `project-onboarding`
+
+| Parameter      | Required | Description                           |
+| -------------- | -------- | ------------------------------------- |
+| `projectPath`  | ✅        | Path to project directory             |
+| `projectName`  | ❌        | Name of the project                   |
+| `projectType`  | ❌        | library/application/service/tool/other |
+| `analysisDepth`| ❌        | quick/standard/deep                   |
+| `includeMemories` | ❌     | Generate project memories (default: true) |
+
+Analyzes project structure, detects technologies, and generates memories for context retention. Based on Serena's onboarding system.
+
+</details>
+
+<details>
+<summary><strong>🔄 Mode Switcher</strong> — Flexible agent operation modes (NEW)</summary>
+
+Usage: `mode-switcher`
+
+| Parameter      | Required | Description                           |
+| -------------- | -------- | ------------------------------------- |
+| `targetMode`   | ✅        | Mode to switch to (planning/editing/analysis/etc.) |
+| `currentMode`  | ❌        | Current active mode                   |
+| `context`      | ❌        | Operating context (desktop-app/ide-assistant/etc.) |
+| `reason`       | ❌        | Reason for mode switch                |
+
+Switches between operation modes with optimized tool sets and prompting strategies. Modes include: planning, editing, analysis, interactive, one-shot, debugging, refactoring, documentation.
+
+</details>
+
 <details>
 <summary><strong>Hierarchical Prompt Builder</strong> — Build structured prompts with clear hierarchies</summary>
 
@@ -205,11 +336,75 @@ Usage: `security-hardening-prompt-builder`
 
 Usage: `mermaid-diagram-generator`
 
-| Parameter     | Required | Description                                                      |
-| ------------- | -------- | ---------------------------------------------------------------- |
-| `description` | ✅        | Description of the system or process to diagram                  |
-| `diagramType` | ✅        | Type: `flowchart`, `sequence`, `class`, `state`, `gantt`, `pie` |
-| `theme`       | ❌        | Visual theme for the diagram                                     |
+Generates Mermaid diagrams with intelligent parsing of descriptions for rich, customizable visualizations.
+
+| Parameter          | Required | Description                                                                                                                                          |
+| ------------------ | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `description`      | ✅        | Description of the system or process to diagram. Be detailed and specific for better diagram generation.                                            |
+| `diagramType`      | ✅        | Type: `flowchart`, `sequence`, `class`, `state`, `gantt`, `pie`, `er`, `journey`, `quadrant`, `git-graph`, `mindmap`, `timeline`                   |
+| `theme`            | ❌        | Visual theme: `default`, `dark`, `forest`, `neutral`                                                                                                 |
+| `direction`        | ❌        | Flowchart direction: `TD`/`TB` (top-down), `BT` (bottom-top), `LR` (left-right), `RL` (right-left)                                                  |
+| `strict`           | ❌        | If true, never emit invalid diagram; use fallback if needed (default: true)                                                                          |
+| `repair`           | ❌        | Attempt auto-repair on validation failure (default: true)                                                                                            |
+| `accTitle`         | ❌        | Accessibility title (added as Mermaid comment)                                                                                                       |
+| `accDescr`         | ❌        | Accessibility description (added as Mermaid comment)                                                                                                 |
+| `customStyles`     | ❌        | Custom CSS/styling directives for advanced customization                                                                                             |
+| `advancedFeatures` | ❌        | Type-specific advanced features (e.g., `{autonumber: true}` for sequence diagrams)                                                                   |
+
+**Enhanced Features:**
+
+- **Intelligent Description Parsing**: All diagram types now parse descriptions to extract relevant entities, relationships, and structures
+- **New Diagram Types**:
+  - `er` - Entity Relationship diagrams for database schemas
+  - `journey` - User journey maps for UX workflows
+  - `quadrant` - Quadrant/priority charts for decision matrices
+  - `git-graph` - Git commit history visualization
+  - `mindmap` - Hierarchical concept maps
+  - `timeline` - Event timelines and roadmaps
+- **Advanced Customization**: Direction control, themes, custom styles, and type-specific features
+- **Smart Fallbacks**: Generates sensible default diagrams when description parsing is ambiguous
+
+**Examples:**
+
+```bash
+# Sequence diagram with participants auto-detected from description
+{
+  "description": "User sends login request to API. API queries Database for credentials. Database returns user data. API responds to User with token.",
+  "diagramType": "sequence",
+  "advancedFeatures": {"autonumber": true}
+}
+
+# Class diagram with relationships extracted
+{
+  "description": "User has id and email. Order contains Product items. User places Order. Product has price and name.",
+  "diagramType": "class"
+}
+
+# ER diagram for database schema
+{
+  "description": "Customer places Order. Order contains LineItem. Product is referenced in LineItem.",
+  "diagramType": "er"
+}
+
+# User journey map
+{
+  "description": "Shopping Journey. Section Discovery: User finds product. User reads reviews. Section Purchase: User adds to cart. User completes checkout.",
+  "diagramType": "journey"
+}
+
+# Gantt chart with tasks from description
+{
+  "description": "Project: Feature Development. Phase Planning: Research requirements. Design architecture. Phase Development: Implement backend. Create frontend. Phase Testing: QA validation.",
+  "diagramType": "gantt"
+}
+
+# Flowchart with custom direction
+{
+  "description": "Receive request. Validate input. Process data. Return response.",
+  "diagramType": "flowchart",
+  "direction": "LR"
+}
+```
 
 </details>
 

package/dist/index.js

@@ -18,6 +18,8 @@ import { CallToolRequestSchema, GetPromptRequestSchema, ListPromptsRequestSchema
 import { getPrompt, listPrompts } from "./prompts/index.js";
 // Import resources
 import { getResource, listResources } from "./resources/index.js";
+// Import tool schemas
+import { promptChainingBuilderSchema, promptFlowBuilderSchema, } from "./schemas/flow-tool-schemas.js";
 import { gapFrameworksAnalyzers } from "./tools/analysis/gap-frameworks-analyzers.js";
 import { strategyFrameworksBuilder } from "./tools/analysis/strategy-frameworks-builder.js";
 import { codeHygieneAnalyzer } from "./tools/code-hygiene-analyzer.js";
@@ -26,12 +28,19 @@ import { guidelinesValidator } from "./tools/guidelines-validator.js";
 import { iterativeCoverageEnhancer } from "./tools/iterative-coverage-enhancer.js";
 import { memoryContextOptimizer } from "./tools/memory-context-optimizer.js";
 import { mermaidDiagramGenerator } from "./tools/mermaid-diagram-generator.js";
+import { modeSwitcher } from "./tools/mode-switcher.js";
 import { modelCompatibilityChecker } from "./tools/model-compatibility-checker.js";
+import { projectOnboarding } from "./tools/project-onboarding.js";
 import { domainNeutralPromptBuilder } from "./tools/prompt/domain-neutral-prompt-builder.js";
 // Import tool implementations
 import { hierarchicalPromptBuilder } from "./tools/prompt/hierarchical-prompt-builder.js";
+import { hierarchyLevelSelector } from "./tools/prompt/hierarchy-level-selector.js";
+import { promptChainingBuilder } from "./tools/prompt/prompt-chaining-builder.js";
+import { promptFlowBuilder } from "./tools/prompt/prompt-flow-builder.js";
+import { promptingHierarchyEvaluator } from "./tools/prompt/prompting-hierarchy-evaluator.js";
 import { securityHardeningPromptBuilder } from "./tools/prompt/security-hardening-prompt-builder.js";
 import { sparkPromptBuilder } from "./tools/prompt/spark-prompt-builder.js";
+import { semanticCodeAnalyzer } from "./tools/semantic-code-analyzer.js";
 import { sprintTimelineCalculator } from "./tools/sprint-timeline-calculator.js";
 const server = new Server({
     name: "ai-agent-guidelines",
@@ -512,22 +521,50 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
             },
             {
                 name: "mermaid-diagram-generator",
-                description: "Generate Mermaid diagrams from text descriptions following best practices",
+                description: "Generate Mermaid diagrams from text descriptions following best practices. Supports advanced diagram types and customization options for richer documentation.",
                 inputSchema: {
                     type: "object",
                     properties: {
                         description: {
                             type: "string",
-                            description: "Description of the system or process to diagram",
+                            description: "Description of the system or process to diagram. Be specific and detailed for better diagram generation.",
                         },
                         diagramType: {
                             type: "string",
-                            enum: ["flowchart", "sequence", "class", "state", "gantt", "pie"],
+                            enum: [
+                                "flowchart",
+                                "sequence",
+                                "class",
+                                "state",
+                                "gantt",
+                                "pie",
+                                "er",
+                                "journey",
+                                "quadrant",
+                                "git-graph",
+                                "mindmap",
+                                "timeline",
+                            ],
                             description: "Type of diagram to generate",
                         },
                         theme: {
                             type: "string",
-                            description: "Visual theme for the diagram",
+                            description: "Visual theme for the diagram (e.g., 'default', 'dark', 'forest', 'neutral')",
+                        },
+                        direction: {
+                            type: "string",
+                            enum: ["TD", "TB", "BT", "LR", "RL"],
+                            description: "Direction for flowcharts: TD/TB (top-down), BT (bottom-top), LR (left-right), RL (right-left)",
+                        },
+                        strict: {
+                            type: "boolean",
+                            description: "If true, never emit invalid diagram; fallback to minimal diagram if needed (default: true)",
+                            default: true,
+                        },
+                        repair: {
+                            type: "boolean",
+                            description: "Attempt auto-repair on diagram validation failure (default: true)",
+                            default: true,
                         },
                         accTitle: {
                             type: "string",
@@ -537,6 +574,14 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
                             type: "string",
                             description: "Accessibility description (added as a Mermaid comment)",
                         },
+                        customStyles: {
+                            type: "string",
+                            description: "Custom CSS/styling directives for advanced customization",
+                        },
+                        advancedFeatures: {
+                            type: "object",
+                            description: "Type-specific advanced features (e.g., {autonumber: true} for sequence diagrams)",
+                        },
                     },
                     required: ["description", "diagramType"],
                 },
@@ -846,7 +891,7 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
             },
             {
                 name: "sprint-timeline-calculator",
-                description: "Calculate optimal development cycles and sprint timelines",
+                description: "Calculate optimal development cycles and sprint timelines with dependency-aware scheduling",
                 inputSchema: {
                     type: "object",
                     properties: {
@@ -864,6 +909,19 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
                             type: "number",
                             description: "Team velocity (story points per sprint)",
                         },
+                        optimizationStrategy: {
+                            type: "string",
+                            enum: ["greedy", "linear-programming"],
+                            description: "Optimization strategy: 'greedy' (default, deterministic bin-packing) or 'linear-programming' (future MILP optimization)",
+                        },
+                        includeMetadata: {
+                            type: "boolean",
+                            description: "Include metadata in output",
+                        },
+                        inputFile: {
+                            type: "string",
+                            description: "Input file reference",
+                        },
                     },
                     required: ["tasks", "teamSize"],
                 },
@@ -934,6 +992,219 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
                     required: ["practiceDescription", "category"],
                 },
             },
+            {
+                name: "semantic-code-analyzer",
+                description: "Perform semantic code analysis to identify symbols, structure, dependencies, and patterns. Inspired by Serena's language server-based approach for precise code understanding.",
+                inputSchema: {
+                    type: "object",
+                    properties: {
+                        codeContent: {
+                            type: "string",
+                            description: "Code content to analyze",
+                        },
+                        language: {
+                            type: "string",
+                            description: "Programming language (auto-detected if not provided)",
+                        },
+                        analysisType: {
+                            type: "string",
+                            enum: ["symbols", "structure", "dependencies", "patterns", "all"],
+                            description: "Type of semantic analysis to perform",
+                        },
+                        includeReferences: {
+                            type: "boolean",
+                            description: "Include external reference links",
+                        },
+                        includeMetadata: {
+                            type: "boolean",
+                            description: "Include metadata section",
+                        },
+                        inputFile: {
+                            type: "string",
+                            description: "Optional input file path",
+                        },
+                    },
+                    required: ["codeContent"],
+                },
+            },
+            {
+                name: "project-onboarding",
+                description: "Perform comprehensive project onboarding including structure analysis, dependency detection, and memory generation. Based on Serena's onboarding system for efficient project familiarization.",
+                inputSchema: {
+                    type: "object",
+                    properties: {
+                        projectPath: {
+                            type: "string",
+                            description: "Path to the project directory",
+                        },
+                        projectName: {
+                            type: "string",
+                            description: "Name of the project",
+                        },
+                        projectType: {
+                            type: "string",
+                            enum: ["library", "application", "service", "tool", "other"],
+                            description: "Type of project",
+                        },
+                        analysisDepth: {
+                            type: "string",
+                            enum: ["quick", "standard", "deep"],
+                            description: "Depth of analysis",
+                        },
+                        includeMemories: {
+                            type: "boolean",
+                            description: "Generate project memories",
+                        },
+                        includeReferences: {
+                            type: "boolean",
+                            description: "Include external reference links",
+                        },
+                        includeMetadata: {
+                            type: "boolean",
+                            description: "Include metadata section",
+                        },
+                    },
+                    required: ["projectPath"],
+                },
+            },
+            {
+                name: "mode-switcher",
+                description: "Switch between different agent operation modes (planning, editing, analysis, debugging, etc.) with tailored tool sets and prompting strategies. Based on Serena's flexible mode/context system.",
+                inputSchema: {
+                    type: "object",
+                    properties: {
+                        currentMode: {
+                            type: "string",
+                            enum: [
+                                "planning",
+                                "editing",
+                                "analysis",
+                                "interactive",
+                                "one-shot",
+                                "debugging",
+                                "refactoring",
+                                "documentation",
+                            ],
+                            description: "Current active mode",
+                        },
+                        targetMode: {
+                            type: "string",
+                            enum: [
+                                "planning",
+                                "editing",
+                                "analysis",
+                                "interactive",
+                                "one-shot",
+                                "debugging",
+                                "refactoring",
+                                "documentation",
+                            ],
+                            description: "Mode to switch to",
+                        },
+                        context: {
+                            type: "string",
+                            enum: [
+                                "desktop-app",
+                                "ide-assistant",
+                                "agent",
+                                "terminal",
+                                "collaborative",
+                            ],
+                            description: "Operating context",
+                        },
+                        reason: {
+                            type: "string",
+                            description: "Reason for mode switch",
+                        },
+                        includeReferences: {
+                            type: "boolean",
+                            description: "Include external reference links",
+                        },
+                        includeMetadata: {
+                            type: "boolean",
+                            description: "Include metadata section",
+                        },
+                    },
+                    required: ["targetMode"],
+                },
+            },
+            {
+                name: "prompting-hierarchy-evaluator",
+                description: "Evaluate prompts using hierarchical taxonomy and provide numeric scoring based on clarity, specificity, completeness, and cognitive complexity. Implements reinforcement learning-inspired evaluation metrics.",
+                inputSchema: {
+                    type: "object",
+                    properties: {
+                        promptText: {
+                            type: "string",
+                            description: "The prompt text to evaluate",
+                        },
+                        targetLevel: {
+                            type: "string",
+                            enum: [
+                                "independent",
+                                "indirect",
+                                "direct",
+                                "modeling",
+                                "scaffolding",
+                                "full-physical",
+                            ],
+                            description: "Expected hierarchy level (if known)",
+                        },
+                        context: {
+                            type: "string",
+                            description: "Additional context about the task",
+                        },
+                        includeRecommendations: {
+                            type: "boolean",
+                            description: "Include improvement recommendations",
+                        },
+                        includeReferences: {
+                            type: "boolean",
+                            description: "Include reference links",
+                        },
+                    },
+                    required: ["promptText"],
+                },
+            },
+            {
+                name: "hierarchy-level-selector",
+                description: "Select the most appropriate prompting hierarchy level (independent, indirect, direct, modeling, scaffolding, full-physical) based on task characteristics, agent capability, and autonomy preferences.",
+                inputSchema: {
+                    type: "object",
+                    properties: {
+                        taskDescription: {
+                            type: "string",
+                            description: "Description of the task the prompt will address",
+                        },
+                        agentCapability: {
+                            type: "string",
+                            enum: ["novice", "intermediate", "advanced", "expert"],
+                            description: "Agent's capability level",
+                        },
+                        taskComplexity: {
+                            type: "string",
+                            enum: ["simple", "moderate", "complex", "very-complex"],
+                            description: "Complexity of the task",
+                        },
+                        autonomyPreference: {
+                            type: "string",
+                            enum: ["low", "medium", "high"],
+                            description: "Desired level of agent autonomy",
+                        },
+                        includeExamples: {
+                            type: "boolean",
+                            description: "Include example prompts for the recommended level",
+                        },
+                        includeReferences: {
+                            type: "boolean",
+                            description: "Include reference links",
+                        },
+                    },
+                    required: ["taskDescription"],
+                },
+            },
+            promptChainingBuilderSchema,
+            promptFlowBuilderSchema,
             {
                 name: "design-assistant",
                 description: "Deterministic, context-driven design assistant with constraint framework for structured design sessions",
@@ -1035,6 +1306,20 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
                 return modelCompatibilityChecker(args);
             case "guidelines-validator":
                 return guidelinesValidator(args);
+            case "semantic-code-analyzer":
+                return semanticCodeAnalyzer(args);
+            case "project-onboarding":
+                return projectOnboarding(args);
+            case "mode-switcher":
+                return modeSwitcher(args);
+            case "prompting-hierarchy-evaluator":
+                return promptingHierarchyEvaluator(args);
+            case "hierarchy-level-selector":
+                return hierarchyLevelSelector(args);
+            case "prompt-chaining-builder":
+                return promptChainingBuilder(args);
+            case "prompt-flow-builder":
+                return promptFlowBuilder(args);
             case "design-assistant": {
                 const result = await designAssistant.processRequest(args);
                 return {