feat(prompt_library): prompts can contain tools and MCP servers (#2725)

Author: olimorris

doc/.vitepress/config.mjs

@@ -170,7 +170,6 @@ export default withMermaid(
             },
             { text: "Events", link: "/usage/events" },
             { text: "Inline Assistant", link: "/usage/inline-assistant" },
-            { text: "Action Palette", link: "/usage/action-palette" },
             { text: "Prompt Library", link: "/usage/prompt-library" },
             { text: "Workflows", link: "/usage/workflows" },
             { text: "UI", link: "/usage/ui" },

doc/codecompanion.txt

@@ -1,4 +1,4 @@
-*codecompanion.txt*        For NVIM v0.11        Last change: 2026 February 06
+*codecompanion.txt*        For NVIM v0.11        Last change: 2026 February 08
 
 ==============================================================================
 Table of Contents                            *codecompanion-table-of-contents*
@@ -562,6 +562,21 @@ CONFIG ~
 - All diff config has moved to `display.diff` (#2600 <https://github.com/olimorris/codecompanion.nvim/pull/2600>)
 
 
+PROMPT LIBRARY ~
+
+- The location of rules within a prompt library item has changed from `opts.rules` to `rules`. They now also support workflows:
+
+>markdown
+    ---
+    name: Oli's test workflow
+    strategy: chat
+    description: Workflow test prompt
+    rules:
+      - test_rule
+    ---
+<
+
+
 V17.33.0 TO V18.0.0      *codecompanion-upgrading-general-v17.33.0-to-v18.0.0*
 
 
@@ -2450,6 +2465,10 @@ Palette - `description` - Description shown in the Action Palette -
 **Prompt sections:** - `## system` - System messages that set the LLM’s
 behaviour - `## user` - User messages containing your requests
 
+In the markdown prompt, above,
+|codecompanion-configuration-prompt-library-with-placeholders| are used to
+inject dynamic content from a visual selection.
+
 
 OPTIONS
 
@@ -2471,12 +2490,11 @@ behaviour:
 - `modes` - Only show in specific modes (`{ "v" }` for visual mode)
 - `placement` - For inline interaction: `new`, `replace`, `add`, `before`, `chat`
 - `pre_hook` - Function to run before the prompt is executed (Lua only)
-- `rules` - Specify a rule group to load with the prompt
 - `stop_context_insertion` - Prevent automatic context insertion
 - `user_prompt` - Get user input before actioning the response
 
 
-PLACEHOLDERS
+WITH PLACEHOLDERS
 
 Placeholders allow you to inject dynamic content into your prompts. In markdown
 prompts, use `${placeholder.name}` syntax:
@@ -2640,6 +2658,13 @@ Context items appear at the top of the chat buffer. URLs are automatically
 cached for you.
 
 
+MCP SERVERS
+
+You can also specify |codecompanion-configuration-mcp| to be loaded with your
+prompt:
+
+
+
 PICKERS
 
 Pickers allow you to create dynamic prompt menus based on runtime data.
@@ -2713,6 +2738,19 @@ the `pre_hook` and assume that is the buffer number you wish any code to be
 streamed into.
 
 
+RULES
+
+You can also specify rules to be loaded with your prompt:
+
+
+
+TOOLS
+
+You can also specify tools to be loaded with your prompt. These can be
+individual tools as well as tool groups:
+
+
+
 WORKFLOWS
 
 Workflows allow you to chain multiple prompts together in a sequence. That is,
@@ -4505,6 +4543,13 @@ function:
 Where `docs` is the `alias` of the prompt.
 
 
+SLASH COMMANDS ~
+
+If your prompt library entries have an `alias` defined then you can invoke them
+using a slash command. In the cmd line `:CodeCompanion /<alias>` or `/<alias>`
+if you’re in the chat buffer.
+
+
 USER INTERFACE                            *codecompanion-usage-user-interface*
 
 CodeCompanion aims to keep any changes to the user’s UI to a minimum.

doc/configuration/prompt-library.md

@@ -147,6 +147,8 @@ Markdown prompts consist of two main parts:
 - `## system` - System messages that set the LLM's behaviour
 - `## user` - User messages containing your requests
 
+In the markdown prompt, above, [placeholders](/configuration/prompt-library#with-placeholders) are used to inject dynamic content from a visual selection.
+
 ### Options
 
 Both markdown and Lua prompts support a wide range of options to customise behaviour:
@@ -241,11 +243,10 @@ opts = {
 - `modes` - Only show in specific modes (`{ "v" }` for visual mode)
 - `placement` - For inline interaction: `new`, `replace`, `add`, `before`, `chat`
 - `pre_hook` - Function to run before the prompt is executed (Lua only)
-- `rules` - Specify a rule group to load with the prompt
 - `stop_context_insertion` - Prevent automatic context insertion
 - `user_prompt` - Get user input before actioning the response
 
-### Placeholders
+### With Placeholders
 
 Placeholders allow you to inject dynamic content into your prompts. In markdown prompts, use `${placeholder.name}` syntax:
 
@@ -515,6 +516,36 @@ I'll think of something clever to put here...
 
 Context items appear at the top of the chat buffer. URLs are automatically cached for you.
 
+#### MCP Servers
+
+You can also specify [MCP servers](/configuration/mcp) to be loaded with your prompt:
+
+::: code-group
+
+````markdown [Markdown]
+---
+name: Prompt with MCP servers
+interaction: chat
+description: A prompt that starts MCP servers
+mcp_servers:
+  - tavily-mcp
+  - filesystem
+---
+````
+
+````lua [Lua]
+["Prompt with MCP servers"] = {
+  interaction = "chat",
+  description = "A prompt that starts MCP servers",
+  mcp_servers = {
+    "tavily-mcp",
+    "filesystem",
+  },
+},
+````
+
+:::
+
 #### Pickers
 
 Pickers allow you to create dynamic prompt menus based on runtime data.
@@ -583,6 +614,66 @@ Pre-hooks allow you to run custom logic before a prompt is executed. This is par
 
 For the inline interaction, the plugin will detect a number being returned from the `pre_hook` and assume that is the buffer number you wish any code to be streamed into.
 
+#### Rules
+
+You can also specify rules to be loaded with your prompt:
+
+::: code-group
+
+````markdown [Markdown]
+---
+name: Prompt with rules
+interaction: chat
+description: A prompt that loads rules
+rules:
+  - default
+  - my_other_rule
+---
+````
+
+````lua [Lua]
+["Prompt with rules"] = {
+  interaction = "chat",
+  description = "A prompt that loads rules",
+  rules = {
+    "default",
+    "my_other_rules",
+  },
+},
+````
+
+:::
+
+#### Tools
+
+You can also specify tools to be loaded with your prompt. These can be individual tools as well as tool groups:
+
+::: code-group
+
+````markdown [Markdown]
+---
+name: Prompt with tools
+interaction: chat
+description: A prompt that loads tools
+tools:
+  - cmd_runner
+  - insert_edit_into_file
+---
+````
+
+````lua [Lua]
+["Prompt with tools"] = {
+  interaction = "chat",
+  description = "A prompt that loads tools",
+  tools = {
+    "cmd_runner",
+    "insert_edit_into_file",
+  },
+},
+````
+
+:::
+
 #### Workflows
 
 Workflows allow you to chain multiple prompts together in a sequence. That is, the first prompt is sent to the LLM, the LLM responds, then the next prompt in the workflow is sent, etc. This can be useful for implementing multi-step processes such as chain-of-thought reasoning or iterative code refinement.

doc/upgrading.md

@@ -18,6 +18,20 @@ CodeCompanion follows [semantic versioning](https://semver.org/) and to avoid br
 - Diff keymaps have moved from `interactions.inline.keymaps` to `interactions.shared.keymaps` ([#2600](https://github.com/olimorris/codecompanion.nvim/pull/2600))
 - All diff config has moved to `display.diff` ([#2600](https://github.com/olimorris/codecompanion.nvim/pull/2600))
 
+### Prompt Library
+
+- The location of rules within a prompt library item has changed from `opts.rules` to `rules`. They now also support workflows:
+
+```markdown
+---
+name: Oli's test workflow
+strategy: chat
+description: Workflow test prompt
+rules:
+  - test_rule
+---
+```
+
 ## v17.33.0 to v18.0.0
 
 ### Config

doc/usage/prompt-library.md

@@ -18,3 +18,7 @@ end, { noremap = true, silent = true })
 
 Where `docs` is the `alias` of the prompt.
 
+## Slash Commands
+
+If your prompt library entries have an `alias` defined then you can invoke them using a slash command. In the cmd line `:CodeCompanion /<alias>` or `/<alias>` if you're in the chat buffer.
+

lua/codecompanion/actions/markdown.lua

@@ -64,10 +64,13 @@ function M.parse_file(path, context)
     context = frontmatter.context or nil,
     description = frontmatter.description or "",
     interaction = frontmatter.interaction,
+    mcp_servers = frontmatter.mcp_servers,
     name = frontmatter.name,
     opts = frontmatter.opts or {},
     path = path,
     prompts = prompts,
+    rules = frontmatter.rules,
+    tools = frontmatter.tools,
   }
 end
 
@@ -127,7 +130,7 @@ function M.parse_frontmatter(content)
     end
   end
 
-  --TODO: Remove in v19.0.0
+  --TODO: Remove in v20.0.0
   if frontmatter.strategy then
     frontmatter.interaction = frontmatter.strategy
     frontmatter.strategy = nil

lua/codecompanion/actions/prompt_library.lua

@@ -35,10 +35,13 @@ function M.resolve(context, config)
       context = prompt.context,
       description = description,
       interaction = prompt.interaction or prompt.strategy,
+      mcp_servers = prompt.mcp_servers,
       name = name,
       opts = prompt.opts,
       picker = prompt.picker,
       prompts = prompt.prompts,
+      rules = prompt.rules,
+      tools = prompt.tools,
     })
 
     ::continue::

lua/codecompanion/interactions/chat/helpers/init.lua

@@ -1,6 +1,8 @@
+local config = require("codecompanion.config")
+
 local Path = require("plenary.path")
 local buf_utils = require("codecompanion.utils.buffers")
-local config = require("codecompanion.config")
+local log = require("codecompanion.utils.log")
 
 local M = {}
 
@@ -89,6 +91,37 @@ function M.has_tag(tag, messages)
   )
 end
 
+---Start MCP servers and add their tools to the chat buffer
+---@param chat CodeCompanion.Chat
+---@param server_names table<string> List of MCP server names
+---@return nil
+function M.start_mcp_servers(chat, server_names)
+  local mcp = require("codecompanion.mcp")
+
+  ---Add an MCP server's tool group to the chat buffer
+  ---@param name string
+  local function add_tools(name)
+    chat.tools:refresh({ adapter = chat.adapter })
+    chat.tool_registry:add(mcp.tool_prefix() .. name, { config = chat.tools.tools_config })
+    log:debug("Added MCP server tools for `%s` to chat %d", name, chat.id)
+  end
+
+  for _, name in ipairs(server_names) do
+    local status = mcp.get_status()
+    local server_status = status[name]
+
+    if server_status and server_status.ready and server_status.tool_count > 0 then
+      add_tools(name)
+    else
+      mcp.enable_server(name, {
+        on_tools_loaded = function()
+          add_tools(name)
+        end,
+      })
+    end
+  end
+end
+
 ---Determine if context has already been added to the messages stack
 ---@param context string
 ---@param messages CodeCompanion.Chat.Messages