Antarpreet/agentic-workflow-mcp

Local Agentic Workflow MCP Server

This MCP server allows you to run the Agentic Workflows using a local LLM server using Ollama CLI. This has been tested for VS Code. The workflows are designed as follows:

For supported workflow example configurations, see the file.

Table of Contents

• Articles
• Prerequisites
• Installation
• Config Settings
• Environment Variables
• MCP Tools
• MCP Resources
• Custom Embeddings for RAG
• Local LLM Tools
• Troubleshooting
• Using Workflows without MCP Server

Articles

• 🧠 How to Set Up a Local Agentic Workflow with MCP and Ollama (Without Losing Your Mind)
• 🧠Create Vector Embeddings for Your Local Agentic Workflow Using an MCP Server (The easy way)

Prerequisites

- Python 3.8 or higher
- pip (for installing Python packages)
- Ollama CLI (for local LLMs)

Installation

1. Clone the repository:

   git clone https://github.com/Antarpreet/agentic-workflow-mcp.git
   

2. Start an LLM server using the ollama CLI. For example, to start the llama3.2:3b model, run:

   ollama run llama3.2:3b
   

   This will start the LLM server on http://localhost:11434 by default.

   If you are using tools in your workflow, please ensure the model you are using supports them: Models supporting tools

   If you will be using local vector embeddings in your workflow, you can also pull the nomic-embed-text model using the following command:

   ollama pull nomic-embed-text
   

   Other embedding models can be found here: Embedding Models.

3. Install the required Python packages:

    pip install -r requirements.txt
   

4. Add MCP Server to VS Code:

   • Open .vscode/mcp.json in your workspace folder. If it doesn't exist, create it.
   • Update PATH_TO_YOUR_CONFIG in the WORKFLOW_CONFIG_PATH environment variable to point to the config file in your workspace folder.

   • The default config uses workspaceFolder environment variable from VS Code to get the path of the workspace.
   • If you would like to use User Settings, make sure to replace the environment variable with the absolute path of your workspace folder.
   • You can open the User settings.json file directly by using the command Preferences: Open User Settings (JSON) in the Command Palette for updating User Settings and add the following config in a mcp object: mcp: { "servers": ... }.
   • The path to the config.json file in the WORKFLOW_CONFIG_PATH environment variable PATH_TO_YOUR_CONFIG should point to the config.json file in your workspace folder. This allows you to use different configurations for different projects.

   // .vscode/mcp.json in your workspace folder
   {
       "servers": {
           "Agentic Workflow": {
               "type": "stdio",
               "command": "python",
               "args": [
                   "-m",
                   "uv",
                   "run",
                   "mcp",
                   "run",
                   // Linux/MacOS
                   "~/agentic-workflow-mcp/server.py"
                   // Windows
                   "%USERPROFILE%\\agentic-workflow-mcp\\server.py"
               ],
               "env": {
                   "WORKSPACE_PATH": "${workspaceFolder}",
                   "WORKFLOW_CONFIG_PATH": "${workspaceFolder}/PATH_TO_YOUR_CONFIG/config.json",
               }
           }
       }
   }
   

5. Add Config for the MCP Server as follows:

   • Use one of the default configurations from config_examples in your config.json file as needed. The config settings are detailed further below. There are example configurations in the config_examples folder. You can use them as a reference to create your own configuration.

   • Copy the server folder to the user folder. (C:\Users\<username>\agentic-workflow-mcp on Windows or ~/agentic-workflow-mcp on Linux/MacOS). This will make it easier to access the server files across different projects. You can do this by running the following commands in your terminal:

     Windows:

     xcopy /E /I agentic-workflow-mcp %USERPROFILE%\agentic-workflow-mcp
     

     Mac/Linux:

     rm -rf ~/agentic-workflow-mcp
     cp -r agentic-workflow-mcp ~/agentic-workflow-mcp
     

   Anytime you make any changes to these files, copy them to the user folder again and restart the MCP server in the .vscode/mcp.json file for the changes to take effect.

6. Start the MCP server:

   • Click the Start button above the MCP server configuration in the .vscode/mcp.json file in your workspace folder.
   • This will start the MCP server; you can see the logs in the Output panel under MCP: Agentic Workflow by clicking either the Running or Error button above the MCP server configuration.

7. Start using the MCP server:

   • Open GitHub Copilot in VS Code and switch to Agent mode.
   • You should see the Agentic Workflow MCP server and start_workflow tool in the Copilot tools panel.
   • You can now start using the MCP tools. Prompt example:

   // This will create a `graph.png` file in your workspace folder.
   // It's recommended to use this before running the workflow
   // to see the graph of the agents and their connections.
   Use MCP Tools to display the graph.
   // This will start the workflow.
   Use MCP Tools to start a workflow to YOUR_PROMPT_HERE.
   // This will create embeddings for the files passed in the prompt.
   Use MCP tool to embed files #file:Readme.md
   // This will create a 2D or 3D visualization of the embeddings
   // for the default collection from the config unless specified in the prompt.
   Use MCP tool to visualize embeddings.
   

Config Settings

Workflow

Agent

Tool

Tool Output

Orchestrator

Evaluator

Edge

Parallel

Branch

Router

Environment Variables

These are the environment variables that are used in the MCP server. You can set them in the .vscode/mcp.json file as shown above.

MCP Tools

display_graph

Generates a graph image from the workflow configuration and saves it to a graph.png file in the workspace folder. This is useful for visualizing the workflow and understanding the connections between agents. It can also generate a mermaid diagram for the workflow.

start_workflow

This tool is used to start the Agentic Workflow. It takes a prompt as input and returns the result of the workflow.

embed_files

This tool creates embeddings for one or more files and stores them in the local ChromaDB vector database. These embeddings can be used using the retrieve_embeddings tool in the agent configuration.

visualize_embeddings

Generates a 2D or 3D visualization of the embeddings in the local ChromaDB vector database. This is useful for understanding the distribution of the embeddings and identifying clusters or patterns in the data.

MCP Resources

These can be accessed using MCP: Browse Resources command in the Command Palette (Ctrl+Shift+P or Cmd+Shift+P on Mac).

get_agents

Returns the list of agents defined in the workflow configuration.

get_state_schema

Returns the state schema defined in the workflow configuration containing both default and user-defined properties.

Custom Embeddings for RAG

Custom Embeddings for your local files can be created using the embed_files tool.

This tool creates embeddings for one or more files and stores them in the local ChromaDB vector database.

The local chroma_vector_db vector database is created in the workspace folder. You can add it to your .gitignore file to avoid committing it to your repository.

If the absolute path to the file is not provided, the tool will look for the file in the workspace folder. The workspace_path variable is set to ${workspaceFolder} by default, which is the path to your workspace folder.

The embeddings are automatically created, updated and deleted when invoking the embed_files tool. delete_missing_embeddings is set to true by default. This means that if a file is deleted from the workspace, its embedding will be deleted from the vector database next time the embed_files tool is invoked.

The local embeddings can be made available to any agent in the chain by using the retrieve_embeddings tool in the agent configuration. This tool will retrieve the embeddings from the local vector database and use them to answer questions.

You can visualize the embeddings using the visualize_embeddings tool. This will create a 2D or 3D visualization of the embeddings in the local ChromaDB vector database. This is useful for understanding the distribution of the embeddings and identifying clusters or patterns in the data.

Local LLM Tools

These are local tools available to the local Ollama LLM server. You can use these tools in your workflow to perform various tasks. These tools will be invoked as part of the workflow so you don't have to worry about calling them separately. The tools are defined in the config.json file and can be used in the workflow by specifying the tool names in the agent config.

You can add your own tools directly in the config.json file as described above.

read_file

Reads the content of a file and returns it as a string.

read_multiple_files

Reads the content of multiple files and returns them as a single string.

read_multiple_files_with_id

Reads the content of multiple files and returns them as an object with file IDs as keys and file contents as values.

list_files

Lists all files in a given directory.

write_file

Writes the given content to a file. Creates directories if they don't exist.

write_file_lines

Write lines content at the specified line numbers to a file. Creates directories if they don't exist.

append_file

Appends the given content to a file. Creates directories if they don't exist.

append_file_lines

Appends lines content at the specified line numbers to a file. Creates directories if they don't exist.

web_search

Performs a web search using DuckDuckGo and returns the results.

api_fetch

Fetch data from an API endpoint.

run_shell_command

Runs a shell command and returns the output.

validate_xml

Validates an XML file against a given XSD schema.

This uses xmllint cli command to validate the XML file. Make sure to install the command for your operating system.

retrieve_embeddings

Fetches the embeddings from the local vector database and uses them to answer questions.

modify_embeddings

Updates the embeddings for the specified files.

Troubleshooting

• If the MCP server is not making any requests to the LLM server, do the following:

  1. Restart VS Code as a sanity check.
  2. Ensure the Ollama LLM server is running and accessible.
  3. Copy the server files again using the commands above, another sanity check.
  4. Restart the MCP server in the .vscode/mcp.json file.
  5. Create a new chat in GitHub Copilot and switch to Agent mode.

• You can check the logs using:

  Windows:

  type %homedrive%%homepath%\agentic-workflow-mcp\logs.txt
  

  Mac/Linux:

  tail -f ~/agentic-workflow-mcp/logs.txt
  

• If you want to clean the local chroma db, you can do by deleting the chroma_vector_db folder in your workspace folder. This will delete all the embeddings and you can start fresh. Make sure to restart the MCP server after deleting the folder in order to initialize the empty database.

Using Workflows without MCP Server

If you want to use the workflows without the MCP server, you can do so by directly importing the python classes as used in the file. This way the workflows can be deployed as a web service to a cloud provider using the same configuration files.