Skip to content

Commit 66cbfd0

Browse files
kevinwguanluarss
kevinwguan
and
luarss
authored
[Feature] MCP Client/Server (#146)
* initial mcp with signature Signed-off-by: Kevin Guan <[email protected]> * updated version for mcp adapters Signed-off-by: Kevin Guan <[email protected]> * major revisions to mcp server Signed-off-by: Kevin Guan <[email protected]> * renamed mcp package to openroad_mcp Signed-off-by: Kevin Guan <[email protected]> * final changes to the mcp server Signed-off-by: Kevin Guan <[email protected]> * updated backend readme for running mcp Signed-off-by: Kevin Guan <[email protected]> * add claude to gitignore Signed-off-by: Jack Luar <[email protected]> * remove unnecessary shebangs Signed-off-by: Jack Luar <[email protected]> * fix checks Signed-off-by: Jack Luar <[email protected]> * update backend .env.example Signed-off-by: Jack Luar <[email protected]> * fix TODO for 3 unpacked values Signed-off-by: Jack Luar <[email protected]> * feat(Makefile, requirements, agents): ✨ Add MCP and chat commands, update dependencies * Introduced new commands in `Makefile` for MCP development and chat functionality. * Updated `requirements.txt` to reflect the latest versions of `fastapi` and `langchain-google-vertexai`. * Refactored `retriever_mcp.py` and `retriever_rag.py` to utilize `get_tools()` for tool management. * Enhanced `client.py` with an asynchronous health check for the MCP server. * Added a health check endpoint in `orfs_server.py` for improved server monitoring. Signed-off-by: Jack Luar <[email protected]> * feat(MCP Agent): ✨ Add MCP Agent Trigger Guide and enhance error handling * Introduced a new `MCP Agent Trigger Guide` to document how the MCP agent is triggered by user queries. * Enhanced the `mcp_info` tool documentation to clarify its usage for executing commands and system operations. * Improved error handling in `retriever_mcp.py` to log specific exceptions during tool invocation. * Refactored `get_tools` function in `client.py` to use asynchronous calls for better performance. * Updated `orfs_server.py` to streamline platform and design retrieval methods. Signed-off-by: Jack Luar <[email protected]> * feat(routing_tools): ✨ Add architecture, MCP, and RAG info tools * Introduced new tools for handling OpenROAD infrastructure and command execution. * Enhanced modularity by separating tool definitions into `routing_tools.py`. * Improved code organization and maintainability. Signed-off-by: Jack Luar <[email protected]> * fix tests Signed-off-by: Jack Luar <[email protected]> * updated readme and removed todo Signed-off-by: Kevin Guan <[email protected]> * disable mcp by default Signed-off-by: Kevin Guan <[email protected]> --------- Signed-off-by: Kevin Guan <[email protected]> Signed-off-by: kevinwguan <[email protected]> Signed-off-by: Jack Luar <[email protected]> Co-authored-by: Jack Luar <[email protected]>
1 parent e839e9b commit 66cbfd0

32 files changed

+1518
-363
lines changed

‎.gitignore‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -44,3 +44,7 @@ node_modules
4444
coverage.xml
4545
report.html
4646
.coverage
47+
48+
# Claude
49+
CLAUDE.md
50+
.claude

‎CLAUDE.md‎

Lines changed: 0 additions & 124 deletions
This file was deleted.

‎backend/.env.example‎

Lines changed: 31 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -1,30 +1,37 @@
11
GOOGLE_API_KEY={{GOOGLE_API_KEY}}
22
GOOGLE_PROJECT_ID={{GOOGLE_PROJECT_ID}}
33
GOOGLE_APPLICATION_CREDENTIALS={{PATH_TO_GOOGLE_APPLICATION_CREDENTIALS}}
4+
GOOGLE_CLOUD_LOCATION=us-central1
5+
6+
# Backend endpoint URL
7+
BACKEND_ENDPOINT=http://localhost:8000
48

59
USE_CUDA=false
610
SEARCH_K=5
711
CHUNK_SIZE=2000
812
CHUNK_OVERLAP=200
913

1014
# Choose between 'gemini' or 'ollama'
11-
LLM_MODEL="gemini"
15+
LLM_MODEL=gemini
1216

1317
# Specify model name if using Ollama
14-
OLLAMA_MODEL=""
18+
OLLAMA_MODEL=
1519

1620
# Set Google Gemini model version
17-
GOOGLE_GEMINI="1.5_flash"
21+
GOOGLE_GEMINI=1.5_flash
1822

1923
LLM_TEMP=1
2024

21-
EMBEDDINGS_TYPE="GOOGLE_VERTEXAI"
22-
GOOGLE_EMBEDDINGS="text-embedding-004"
23-
HF_EMBEDDINGS="thenlper/gte-large"
24-
HF_RERANKER="BAAI/bge-reranker-base"
25+
EMBEDDINGS_TYPE=GOOGLE_VERTEXAI
26+
GOOGLE_EMBEDDINGS=text-embedding-004
27+
HF_EMBEDDINGS=thenlper/gte-large
28+
HF_RERANKER=BAAI/bge-reranker-base
29+
30+
# FAISS database path
31+
FAISS_DB_PATH=./.faissdb/faiss_index
2532

2633
LANGSMITH_TRACING=true
27-
LANGSMITH_ENDPOINT="https://api.smith.langchain.com"
34+
LANGSMITH_ENDPOINT=https://api.smith.langchain.com
2835
LANGSMITH_API_KEY=
2936
LANGSMITH_PROJECT=
3037

@@ -35,13 +42,25 @@ TOKENIZERS_PARALLELISM=false
3542
LOGLEVEL="INFO"
3643

3744
BACKEND_WORKERS=4
38-
BACKEND_URL="0.0.0.0"
45+
BACKEND_URL=0.0.0.0
3946

4047
# Set FAST_MODE=true for fast prototyping
4148
FAST_MODE=false
4249

50+
# Debug mode for development
51+
DEBUG=false
52+
53+
# MCP Server Configuration
54+
# Path to OpenROAD Flow Scripts directory
55+
ORFS_DIR={{PATH_TO_ORFS_DIR}}
56+
57+
# Repository commit hashes for documentation building
58+
OR_REPO_COMMIT=ffc5760f2df639cd184c40ceba253c7e02a006d5
59+
ORFS_REPO_COMMIT={{ORFS_REPO_COMMIT}}
60+
OPENSTA_REPO_COMMIT={{OPENSTA_REPO_COMMIT}}
61+
4362
# Set healthcheck parameters
44-
HEALTHCHECK_INTERVAL="30s"
45-
HEALTHCHECK_TIMEOUT="10s"
63+
HEALTHCHECK_INTERVAL=30s
64+
HEALTHCHECK_TIMEOUT=10s
4665
HEALTHCHECK_RETRIES=5
47-
HEALTHCHECK_START_PERIOD="1200s"
66+
HEALTHCHECK_START_PERIOD=1200s

‎backend/MCP_AGENT_TRIGGER.md‎

Lines changed: 94 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,94 @@
1+
# MCP Agent Trigger Guide
2+
3+
## Overview
4+
The MCP (Model Context Protocol) agent is triggered when users want to run commands or perform shell/system actions related to OpenROAD infrastructure. It connects to an MCP server running on `http://localhost:3001/mcp/` to execute ORFS (OpenROAD-Flow-Scripts) commands.
5+
6+
## How MCP Agent Gets Triggered
7+
8+
### 1. Query Classification
9+
When a user sends a query, the system first classifies it into one of three categories:
10+
- **rag_info**: Information retrieval from documentation
11+
- **mcp_info**: Command execution or shell actions
12+
- **arch_info**: Generate OpenROAD infrastructure files
13+
14+
The MCP agent is triggered when the query is classified as `mcp_info`.
15+
16+
### 2. Trigger Keywords and Patterns
17+
The MCP agent is typically triggered by queries that:
18+
- Request to **run** or **execute** commands
19+
- Involve **terminal** or **shell** operations
20+
- Request **system actions** or **environment changes**
21+
- Include action verbs like: run, execute, perform, start, launch, build, compile
22+
23+
## Example Queries That Trigger MCP Agent
24+
25+
### Command Execution
26+
```
27+
"Run synthesis on my design"
28+
"Execute the floorplan command"
29+
"Start the placement flow"
30+
"Build my RTL design with Yosys"
31+
"Compile the Verilog files"
32+
```
33+
34+
### Shell/Terminal Actions
35+
```
36+
"Show me the ORFS environment variables"
37+
"Check the current OpenROAD version"
38+
"List available ORFS make targets"
39+
"Run make in the design directory"
40+
```
41+
42+
### System Operations
43+
```
44+
"Set up the OpenROAD environment"
45+
"Configure the design parameters"
46+
"Initialize a new ORFS project"
47+
"Clean the build directory"
48+
```
49+
50+
## Example Queries That DON'T Trigger MCP (Go to RAG Instead)
51+
52+
### Information Queries
53+
```
54+
"What is OpenROAD?"
55+
"How does placement work?"
56+
"Explain the synthesis flow"
57+
"What are the available PDKs?"
58+
"Tell me about timing analysis"
59+
```
60+
61+
### Documentation Requests
62+
```
63+
"Show me the documentation for global placement"
64+
"What are the parameters for detailed routing?"
65+
"How to use the timing report commands?"
66+
```
67+
68+
## MCP Server Requirements
69+
70+
For the MCP agent to work:
71+
1. MCP server must be running at `http://localhost:3001`
72+
2. Health check endpoint must be available at `/health`
73+
3. Server must provide ORFS command tools via the MCP protocol
74+
75+
## Technical Flow
76+
77+
1. **Classification**: Query classified as `mcp_info` in `retriever_graph.py`
78+
2. **Agent Selection**: Routes to `mcp_agent` method
79+
3. **Tool Binding**: Fetches available tools from MCP server via `get_tools()`
80+
4. **Execution**: Uses LLM with tool calling to select and execute appropriate command
81+
5. **Response**: Returns command output to user
82+
83+
## Debugging MCP Agent Triggers
84+
85+
To see which agent is triggered:
86+
- Check logs for classification result (will show "mcp_agent" for MCP)
87+
- Look for "Successfully connected to MCP server" message
88+
- Monitor tool calls being made to the MCP server
89+
90+
## Notes
91+
92+
- MCP agent requires LLMs with tool-calling capabilities (e.g., Llama 3.1, GPT-4)
93+
- If MCP server is unavailable, queries may fall back to RAG agent
94+
- The classification uses either built-in tool calling or prompt-based classification depending on LLM capabilities

‎backend/Makefile‎

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -31,3 +31,14 @@ build-docs:
3131
test:
3232
@. .venv/bin/activate && \
3333
pytest
34+
35+
# For MCP Development
36+
.PHONY: mcp
37+
mcp:
38+
@. .venv/bin/activate && \
39+
python -m src.openroad_mcp.server.orfs.orfs_server
40+
41+
.PHONY: chat
42+
chat:
43+
@. .venv/bin/activate && \
44+
python -m chatbot

‎backend/README.md‎

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -61,6 +61,8 @@ ORAssistant supports running locally hosted Ollama models for inference. Follow
6161

6262
Ensure Ollama is running locally before starting ORAssistant. Make sure the model weights are available by downloading them first with `ollama pull <model_name>`.
6363

64+
To take advantage of GPU resources when running ORAssistant in a Docker container, use `ollama serve` on local machine.
65+
6466
### Setting Up LangChain Variables
6567

6668
There are 4 variables that needs to be set up
@@ -129,3 +131,10 @@ docker build -t (image_name) .
129131
Make sure you are in the backend folder before running the above command.
130132
131133
**NOTE**: The project does support a `docker-compose` file that would run all of the containers together
134+
135+
### MCP Commands
136+
OpenROAD's MCP server is a wrapper around the OpenROAD-flow-scripts. It utilizes the Streamable HTTP transport so it must be launched as a separate process. Run with `python orfs_server.py`
137+
138+
Currently tested with running `python chatbot.py` in another process.
139+
140+
Note: mcp breaks support for llms without toolchain i.e. json parsing

0 commit comments

Comments
 (0)