diff --git a/docs/content/advanced/images/export.png b/docs/content/advanced/images/export.png index 229efce2..27a06c3f 100644 Binary files a/docs/content/advanced/images/export.png and b/docs/content/advanced/images/export.png differ diff --git a/docs/content/advanced/langchain_mcp.md b/docs/content/advanced/langchain_mcp.md index 18faa4e5..662f6322 100644 --- a/docs/content/advanced/langchain_mcp.md +++ b/docs/content/advanced/langchain_mcp.md @@ -15,6 +15,24 @@ This document describe how to re-use the configuration tested in the **AI Optimi **NOTICE**: Only `Ollama` or `OpenAI` configurations are currently supported. Full support will come. +## Export config +In the **AI Optimizer & Toolkit** web interface, after have tested a configuration, in `Settings/Client Settings`: + +![Client Settings](./images/export.png) + +and **ONLY** if have been selected `Ollama` or `OpenAI` providers for **both** chat and embeddings models: + +* select the checkbox `Include Sensitive Settings` +* press button `Download LangchainMCP` to download a zip file containing a full project template to run current selected AI Optimizer configuration. +* unzip the file in a dir. + +To run it, follow the next steps. + +**NOTICE**: +* if you want to run the application in another server, remember to change in the optimizer_settings.json any reference no more local, like hostname for LLM servers, Database, wallet dir and so on. +* if you don't see the `Download LangchainMCP` check again if you have selected Ollama or OpenAI for both chat and the vectorstore embedding model. + + ## Pre-requisites. You need: - Node.js: v20.17.0+ @@ -23,7 +41,7 @@ You need: - Claude Desktop free ## Setup -With **[`uv`](https://docs.astral.sh/uv/getting-started/installation/)** installed, run the following commands in your current project directory `/src/client/mcp/rag/`: +With **[`uv`](https://docs.astral.sh/uv/getting-started/installation/)** installed, run the following commands in your current project directory ``: ```bash uv init --python=3.11 --no-workspace @@ -32,147 +50,105 @@ source .venv/bin/activate uv add mcp langchain-core==0.3.52 oracledb~=3.1 langchain-community==0.3.21 langchain-huggingface==0.1.2 langchain-openai==0.3.13 langchain-ollama==0.3.2 ``` -## Export config -In the **AI Optimizer & Toolkit** web interface, after tested a configuration, in `Settings/Client Settings`: - -![Client Settings](./images/export.png) - -* select the checkbox `Include Sensitive Settings` -* press button `Download Settings` to download configuration in the project directory: `src/client/mcp/rag` as `optimizer_settings.json`. -* in `/src/client/mcp/rag/rag_base_optimizer_config_mcp.py` change filepath with the absolute path of your `optimizer_settings.json` file. - - ## Standalone client -There is a client that you can run without MCP via commandline to test it: - -```bash -uv run rag_base_optimizer_config.py -``` -## Quick test via MCP "inspector" - -* Run the inspector: +There is a client that let you run the service via command-line, to test it without an MCP client, in your ``: ```bash -npx @modelcontextprotocol/inspector uv run rag_base_optimizer_config_mcp.py -``` - -* connect to the port `http://localhost:6274/` with your browser -* setup the `Inspector Proxy Address` with `http://127.0.0.1:6277` -* test the tool developed. - - -## Claude Desktop setup - -* In **Claude Desktop** application, in `Settings/Developer/Edit Config`, get the `claude_desktop_config.json` to add the references to the local MCP server for RAG in the `/src/client/mcp/rag/`: -```json -{ - "mcpServers": { - ... - , - "rag":{ - "command":"bash", - "args":[ - "-c", - "source /src/client/mcp/rag/.venv/bin/activate && uv run /src/client/mcp/rag/rag_base_optimizer_config_mcp.py" - ] - } - } -} +uv run rag_base_optimizer_config_direct.py "[YOUR_QUESTION]" ``` -* In **Claude Desktop** application, in `Settings/General/Claude Settings/Configure`, under `Profile` tab, update fields like: -- `Full Name` -- `What should we call you` - - and so on, putting in `What personal preferences should Claude consider in responses?` - the following text: - -``` -#INSTRUCTION: -Always call the rag_tool tool when the user asks a factual or information-seeking question, even if you think you know the answer. -Show the rag_tool message as-is, without modification. -``` -This will impose the usage of `rag_tool` in any case. - -**NOTICE**: If you prefer, in this agent dashboard or any other, you could setup a message in the conversation with the same content of `Instruction` to enforce the LLM to use the rag tool as well. - -* Restart **Claude Desktop**. -* You will see two warnings on rag_tool configuration: they will disappear and will not cause any issue in activating the tool. - -* Start a conversation. You should see a pop up that ask to allow the `rag` tool usage to answer the questions: - -![Rag Tool](./images/rag_tool.png) - - If the question is related to the knowledge base content stored in the vector store, you will have an answer based on that information. Otherwise, it will try to answer considering information on which has been trained the LLM o other tools configured in the same Claude Desktop. - - -## Make a remote MCP server the RAG Tool +## Run the RAG Tool by a remote MCP server In `rag_base_optimizer_config_mcp.py`: -* Update the absolute path of your `optimizer_settings.json`. Example: +* Check if configuration is like this for the clients (`Remote client`) in the following lines, otherwise change as shown: ```python -rag.set_optimizer_settings_path("/Users/cdebari/Documents/GitHub/ai-optimizer-mcp-export/src/client/mcp/rag/optimizer_settings.json") +# Initialize FastMCP server +mcp = FastMCP("rag",host="0.0.0.0", port=9090) #Remote client +#mcp = FastMCP("rag") #Local ``` -* Substitute `Local` with `Remote client` line: - -```python -#mcp = FastMCP("rag", port=8001) #Remote client -mcp = FastMCP("rag") #Local -``` +* Check, or change, according following lines of code: -* Substitute `stdio` with `sse` line of code: ```python -mcp.run(transport='stdio') -#mcp.run(transport='sse') + #mcp.run(transport='stdio') + #mcp.run(transport='sse') + mcp.run(transport='streamable-http') ``` * Start MCP server in another shell with: + ```bash uv run rag_base_optimizer_config_mcp.py ``` - -## Quick test +## Quick test via MCP "inspector" * Run the inspector: ```bash -npx @modelcontextprotocol/inspector +npx @modelcontextprotocol/inspector@0.15.0 ``` -* connect the browser to `http://127.0.0.1:6274` +* connect to the linke report like this: -* set the Transport Type to `SSE` - -* set the `URL` to `http://localhost:8001/sse` +``` + http://localhost:6274/?MCP_PROXY_AUTH_TOKEN=1b40988bb02624b74472a9e8634a6d78802ced91c34433bf427cb3533c8fee2c +``` -* test the tool developed. +* setup the `Transport Type` to `Streamable HTTP` +* test the tool developed, setting `URL` to `http://localhost:9090/mcp`. +## Claude Desktop setup -## Claude Desktop setup for remote/local server Claude Desktop, in free version, not allows to connect remote server. You can overcome, for testing purpose only, with a proxy library called `mcp-remote`. These are the options. -If you have already installed Node.js v20.17.0+, it should work: - -* replace `rag` mcpServer, setting in `claude_desktop_config.json`: -```json -{ - "mcpServers": { - "remote": { +If you have already installed Node.js v20.17.0+, it should work. + +* In **Claude Desktop** application, in `Settings/Developer/Edit Config`, get the `claude_desktop_config.json` to add the reference to the local MCP server for RAG in `streamable-http`: + ```json + { + "mcpServers": { + ... + , + "rag":{ "command": "npx", "args": [ "mcp-remote", - "http://127.0.0.1:8001/sse" - ] - } - } -} -``` -* restart Claude Desktop. + "http://127.0.0.1:9090/mcp" + ] + } + } + } + ``` + + +* In **Claude Desktop** application, in `Settings/General/Claude Settings/Configure`, under `Profile` tab, update fields like: + + - `Full Name` + - `What should we call you` + + and so on, putting in `What personal preferences should Claude consider in responses?` + the following text: + + ``` + #INSTRUCTION: + Always call the rag_tool tool when the user asks a factual or information-seeking question, even if you think you know the answer. + Show the rag_tool message as-is, without modification. + ``` + This will impose the usage of `rag_tool` in any case. + +* Restart **Claude Desktop**. + +* You will see two warnings on rag_tool configuration: they will disappear and will not cause any issue in activating the tool. + +* Start a conversation. You should see a pop up that ask to allow the `rag` tool usage to answer the questions: + +![Rag Tool](./images/rag_tool.png) + + If the question is related to the knowledge base content stored in the vector store, you will have an answer based on that information. Otherwise, it will try to answer considering information on which has been trained the LLM o other tools configured in the same Claude Desktop. **NOTICE**: If you have any problem running, check the logs if it's related to an old npx/nodejs version used with mcp-remote library. Check with: ```bash