mcpn

<p align="center"> <picture align="center"> <!-- <source media="(prefers-color-scheme: dark)" srcset="./public/banner.png"> --> <img align="center" alt="mcpn Banner Main" src="./public/banner.png" width="560"> </picture> </p> <p align="center"> <strong> <em>mcpn.ai</em> helps you create, organize, and share AI workflows and prompts. <br>Like a dynamic prompt library you can share & version across MCP tools and servers for specific tasks. </strong> </p> <p align="center"> <img alt="NPM Downloads" src="https://img.shields.io/npm/dx-zero/mcpn?style=flat-square&logo=npm"> <img alt="jsDelivr hits (npm)" src="https://img.shields.io/jsdelivr/npm/dx-zero/mcpn?style=flat-square&logo=jsdeliver"> <img alt="GitHub Sponsors" src="https://img.shields.io/github/sponsors/dx-zero/mcpn?style=flat-square&logo=github"> <br /> <strong>Created by</strong><br /> <a href="https://twitter.com/tedx_ai"> <img src="https://img.shields.io/twitter/follow/tedx_ai?style=social" alt="Follow @tedx_ai on Twitter"> </a> <a href="https://twitter.com/kregenrek"> <img src="https://img.shields.io/twitter/follow/kregenrek?style=social" alt="Follow @kregenrek on Twitter"> </a> </p> ## Usage Basic Example <table> <tr> <td style="width:50%; vertical-align:top;"> ```yaml plan_prd: description: "Create a product requirements..." prompt: | You are an expert product manager/business analyst and are now entering "PRD Mode" Begin by deeply reflecting upon the notes, requirements and images provided... tools: createPRD, createStoriesFromPRD, createRoadmap coding_max: description: "Highly effective Coding Agent" prompt: | You are now entering "Developer Mode" - deeply reflect upon the changes being asked and analyze existing code to map the full scope... tools: getConsoleLogs, getErrorLogs, getLinter ... ``` </td> <td style="width:50%; vertical-align:top;"> <img align="center" alt="Example" src="./public/templates.jpg" width="400 "> </td> </tr> </table> Workflows MCP (mcpn) are the building blocks of software development, an orchestration of multiple MCP servers and prompts. Think of it like a dynamic prompting library that you can easily share and version control through yaml files that also lets you define how to best use many MCP tools across many MCP servers for specific tasks. ## Installation Install the MCP server into an MCP client using the following command or JSON: ```bash npx -y mcpn@latest init ``` If using JSON in Cursor to setup your MCP server, you can use the following config: ```json { "mcpServers": { "workflows-mcp": { "command": "npx", "args": ["-y", "mcpn@latest server"] } } } ``` ## Documentation Documentation: [https://mcpn.ai](https://mcpn.ai) ## Examples ... TBD ## License ... TBD ## Links ... TBD ======================================================================== Move below to documentation ## Overview The key to effective MCP use is to know when/how to use the right tools. Workflows MCP helps make this process MUCH easier and faster. With Workflows MCP, you can: ✅ Combine prompts with MCP servers into reusable & easy to edit/share/organize workflows ✅ Trigger workflows with custom commands like: "enter debugger mode" or "use thinking mode" ✅ Define custom strategies for how to use many tools in a workflow (sequential or situational/dynamic) ✅ Easily onboard your team to the best prompts + ways to use many MCP tools w/ version control. _We also provide a number of useful presets to get you started 🫡_ ### So why use this? The goal of this project is to turn prompts into programmable tools and rules for AI in a code editor more deterministic while reducing the overall amount of token use across all requests. Since stuffing a global set of rules for AI can eat up your context window, using MCP to route to prompts and workflows can help reduce the overall amount of tokens used across all requests. Workflows for MCP are also **incredibly** powerful! For instance, you can create an **"production incident workflow"** tool that has a special system prompt to reason about an incident in a particular way and then use a series of tools in a specific order to analyze + potentially resolve the incident. This may involve things like: - Gathering logs across many MCP tools for Kubernetes, Cloudwatch, Splunk, etc - Checking Github issues or a vector database for similar issues in the past - Perform web searches for useful information on the web - Analyze your code with all the gathered context from the prior steps - Write a detailed incident report with all the context from the prior steps - Gather input from you to better understand the problem space - Implement a fix for issue if possible And since these workflows are all defined in YAML and can be referenced from anywhere on your machine, you can **easily** rally your team around when/how to use the best prompts and sequences of MCP tools for specific tasks 🦾 ## Features ### 📝 Custom Configuration - Load custom configs from multiple YAML files in a `.workflows` or `.mcp-workflows` directory - Easily save these yaml files to a git repo and share with your team - Since MCP servers can have custom configs for each project, you can easily pick and choose which configs to use for each project - setting up custom workflow folders for each project - Support for typed parameter inputs in tool configurations makes building custom MCP prompting tools a breeze ### 🚀 Ready-to-Use Presets Workflows MCP includes multiple preset workflow modes out of the box for thinking, coding, and github use: **Thinking**: General purpose tools to improve reasoning on any task - **Thinking Mode**: Reflect on thoughts and produce structured analysis (inspired by Anthropic's latest research into thinking tools) - **Deep Thinking Mode**: Comprehensive multi-perspective analysis with detailed reflections **Coding**: Universally applicable tools for common coding tasks Universally applicable tools for common coding tasks - **Debugger Mode**: Systematic multi-step reasoning and debugging with hypothesis creation, telemetry gathering and testing - **Architecture Mode**: System design prompt with tradeoff analysis and implementation planning - **Planner Mode**: Systematic code change planning with codebase analysis - **PRD Mode**: Structured product requirements documentation for features, user stories and spike analysis - **Save Note**: Document ongoing work with comprehensive progress tracking. Useful for when you need to step away for a bit and want to save your thoughts for later. **GitHub**: Tools to simplify common GitHub tasks. Great for anyone who is a beginner with source control using Git and the Github CLI - **PR Review Mode**: Comprehensive pull request analysis with security considerations - **PR Creation Mode**: Structured PR creation process using GitHub CLI - **Create Branch**: Smart branch creation with contextual naming - **Save Changes**: Systematic git commit and push workflow ## Installation Install the MCP server into an MCP client using the following command or JSON: ```bash npx -y mcpn@latest init ``` If using JSON in Cursor to setup your MCP server, you can use the following config: ```json { "mcpServers": { "workflows-mcp": { "command": "npx", "args": ["-y", "mcpn@latest server"] } } } ``` To provide custom configurations, you can use the `--config` flag to point to a directory containing YAML configuration files. The directory must be named `.workflows` or `.mcp-workflows` as so: ```bash npx mcpn@latest server --config /path/to/.workflows ``` If you want to enable presets, you can use the `--preset` flag to specify which presets to load: ```bash npx mcpn@latest server --preset thinking,coding,github ``` Here's what this would look like in a Cursor config all combined: ```json { "mcpServers": { "workflows-mcp": { "command": "npx", "args": [ "mcpn@latest server", "--config", "/path/to/.workflows", "--preset", "thinking,coding" ] } } } ``` Note: - _If you update your config, you must refresh the MCP tool_ - _If refreshing doesn't work, make sure your config is valid YAML_ - _If you're still having issues, then try removing & renaming the MCP tool in your client_ - _If no config or preset is provided, it will default to using the `thinking` preset._ - _If you're still not able to get this working, open an issue ticket_ ## Custom Workflow Configs Create a `.workflows` or `.mcp-workflows` directory in your project and add YAML configuration files with any name (must end with `.yaml` or `.yml`). These configurations will also override the preset defaults if named the same as a preset tool. ### Example Configuration Files #### Basic Workflow Configuration ```yaml workflow_name: description: "Description of what this workflow does" prompt: | Enter your multi-line prompt here like this toolMode: "situational" # can be omitted as it's the default tools: "analyzeLogs, generateReport, validateFindings" ``` #### Tools Configuration Styles You can define tools in several ways. Here's an example of a tool that debugs a problem in a codebase with tools used situationally / as needed: ```yaml web_debugger_mode: description: Debug my codebase my web application with browser logs and BrowserTools MCP prompt: | Deeply reflect upon all of this and think about why this isn't working. Theorize 4-6 different possible sources of the problem. Then, deeply reason about the root cause and distill your theories down to the 1-2 most probable sources of the problem before suggesting next steps. tools: getConsoleLogs, getConsoleErrors, getNetworkLogs, getNetworkErrors, takeScreenshot ``` This will return the following MCP response: ``` Deeply reflect upon all of this and think about why this isn't working. Theorize 4-6 different possible sources of the problem. ## Available Tools Use these tools as needed to complete the user's request: - getConsoleLogs - getConsoleErrors - getNetworkLogs - getNetworkErrors - takeScreenshot After using each tool, return a 'Next Steps' section with a list of the next steps to take / remaining tools to invoke along with each tool's prompt/description and 'optional' flag if present. ``` #### Parameter Injection A powerful feature is the ability to inject parameters into your prompts using the `{{ parameter_name }}` syntax: ```yaml custom_mode: description: "Workflow with parameter injection" parameters: thought: type: "string" description: "A thought to deeply reflect upon" required: true idea: type: "string" description: "An additional idea to consider" prompt: | Deeply reflect upon the provided thought. Here's the thought: {{ thought }} Additional idea to consider: {{ idea }} Reflect upon the implications/tradeoffs it may have as it relates to my current goals. ``` Parameters are automatically validated based on their type definitions and injected into your prompts at runtime. #### Sequential Tool Configuration In sequential mode, tools are executed in a specific order: ```yaml web_debugger_mode: description: Debug my codebase my web application with browser logs and BrowserTools MCP prompt: | Deeply reflect upon all of this and think about why this isn't working. Theorize 4-6 different possible sources of the problem. toolMode: sequential tools: getConsoleLogs, getConsoleErrors, getNetworkLogs, getNetworkErrors, takeScreenshot ``` This will return the following MCP response: ``` Deeply reflect upon all of this and think about why this isn't working. Theorize 4-6 different possible sources of the problem. ## Available Tools If all required user input/feedback is acquired or if no input/feedback is needed, execute this exact sequence of tools to complete this task: 1. getConsoleLogs 2. getConsoleErrors 3. getNetworkLogs 4. getNetworkErrors 5. takeScreenshot After using each tool, return a 'Next Steps' section with a list of the next steps to take / remaining tools to invoke along with each tool's prompt/description and 'optional' flag if present. ``` ### Advanced Tool Configuration Includes ability to define prompts for each tool and an optional flag to indicate if the tool is optional or not in the sequence: ```yaml deep_thinking_mode: description: Reflect on a thought and produce a reflection/new set of thoughts parameters: thought: type: string description: A thought to deeply reflect upon required: true prompt: | Deeply reflect upon the provided thought. Reflect upon the implications/tradeoffs it may have as it relates to my current goals, challenges and our conversation. Do not change anything in our system, just return some thoughts/considerations/analysis based on your reflection of the provided thought. toolMode: "sequential" tools: analyze_thought: analyze a previously generated thought explore_perspectives: think about additional perspectives given the analysis apply_findings: propmt: implement the findings of the analysis optional: true ``` ### Configuration Structure Each YAML file should contain a mapping of tool names to their configuration. Configurations can be loaded from two sources: 1. Internal presets (located in the `presets` directory) 2. User-defined configurations (in `.workflows` or `.mcp-workflows` directory) ### Basic Tool Configuration For each tool, you can specify: - `name`: Optional name override for the registered tool (default is the config key) - `description`: Description of what the workflow/tool does - `prompt`: Custom prompt (completely replaces default prompt if workflow name is also an active preset) - `context`: Additional context to append to the prompt (does not replace default prompt for presets) - `tools`: Array or object of tools available in this mode, with flexible definition styles - `toolMode`: Mode of tool execution, either "sequential" or "situational" (defaults to "situational") - `parameters`: Object mapping of parameters as input to the tool - supports template injection using {{ parameter_name }} - `disabled`: Boolean to disable the tool ### Input Parameter Configuration Tools can accept typed parameters that an MCP Client / agent can provide to improve reasoning capabilities for your prompt/workflow. These inputs are automatically converted to Zod schemas for validation and type safety. Each parameter is defined with the following properties: | Property | Description | Required | | ------------- | ---------------------------------------------------------------------- | ------------------------ | | `type` | Data type: "string", "number", "boolean", "array", "object", or "enum" | Yes | | `description` | Human-readable description of the parameter | No | | `required` | Whether the parameter is required | No (defaults to `false`) | | `default` | Default value if not provided | No | | `enum` | Array of valid values (required for `enum` type only) | Yes (for `enum` type) | | `items` | For array types, defines the type of items in the array | No | | `properties` | For object types, defines the properties of the object | No | #### Example Input Parameter Types ``` ```