Merge pull request #195 from oracle-samples/docs

Docs update for

Author: corradodebari

docs/content/advanced/images/export.png

@@ -0,0 +1,188 @@
++++
+title = 'Export as MCP Langchain server'
+weight = 1
++++
+
+<!--
+Copyright (c) 2024, 2025, Oracle and/or its affiliates.
+Licensed under the Universal Permissive License v1.0 as shown at http://oss.oracle.com/licenses/upl.
+-->
+
+**Version:** *Developer preview*
+
+## Introduction to the MCP Server for a tested AI Optimizer & Toolkit configuration
+This document describe how to re-use the configuration tested in the **AI Optimizer & Toolkit** an expose it as an MCP tool to a local **Claude Desktop** and how to setup as a remote MCP server, through **Python/Langchain** framework. This early draft implementation utilizes the `stdio` and `sse` to interact between the agent dashboard, represented by the **Claude Desktop**, and the tool. 
+
+**NOTICE**: Only `Ollama` or `OpenAI` configurations are currently supported. Full support will come.
+
+## Pre-requisites.
+You need:
+- Node.js: v20.17.0+
+- npx/npm: v11.2.0+
+- uv: v0.7.10+
+- Claude Desktop free
+
+## Setup
+With **[`uv`](https://docs.astral.sh/uv/getting-started/installation/)** installed, run the following commands in your current project directory `<PROJECT_DIR>/src/client/mcp/rag/`:
+
+```bash
+uv init --python=3.11 --no-workspace
+uv venv --python=3.11
+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 `<PROJECT_DIR>/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:
+
+```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 `<PROJECT_DIR>/src/client/mcp/rag/`:
+```json
+{
+ "mcpServers": {
+	...
+	,
+	"rag":{
+		"command":"bash",
+		"args":[
+			"-c",
+			"source <PROJECT_DIR>/src/client/mcp/rag/.venv/bin/activate && uv run <PROJECT_DIR>/src/client/mcp/rag/rag_base_optimizer_config_mcp.py"
+		]
+	}
+   }
+}
+```
+* 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
+
+In `rag_base_optimizer_config_mcp.py`:
+
+* Update the absolute path of your `optimizer_settings.json`. Example:
+
+```python
+rag.set_optimizer_settings_path("/Users/cdebari/Documents/GitHub/ai-optimizer-mcp-export/src/client/mcp/rag/optimizer_settings.json")
+```
+
+* Substitute `Local` with `Remote client` line:
+
+```python
+#mcp = FastMCP("rag", port=8001) #Remote client
+mcp = FastMCP("rag") #Local
+```
+
+* Substitute `stdio` with `sse` line of code:
+```python
+mcp.run(transport='stdio')
+#mcp.run(transport='sse')
+```
+
+* Start MCP server in another shell with:
+```bash
+uv run rag_base_optimizer_config_mcp.py
+```
+
+
+## Quick test
+
+* Run the inspector:
+
+```bash
+npx @modelcontextprotocol/inspector 
+```
+
+* connect the browser to `http://127.0.0.1:6274` 
+
+* set the Transport Type to `SSE`
+
+* set the `URL` to `http://localhost:8001/sse`
+
+* test the tool developed.
+
+
+
+## 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": {
+			"command": "npx",
+			"args": [
+				"mcp-remote",
+				"http://127.0.0.1:8001/sse"
+			]
+		}
+  }
+}
+```
+* restart 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
+nvm -list
+```
+if you have any other versions available than the default. It could happen that Claude Desktop uses the older one. Try to remove any other nvm versions available to force the use the only one avalable, at minimum v20.17.0+.
+
+* restart and test as remote server
+
+
+{{% notice style="code" title="Documentation is Hard!" icon="circle-info" %}}
+More information coming soon... 25-June-2025
+{{% /notice %}}

docs/content/advanced/images/rag_tool.png

@@ -29,11 +29,25 @@ You have simply to:
 chmod 755 ./start.sh
 ```
 
-* add the password for the user used to connect from the {{< short_app_ref >}} to the Oracle DB23ai used as vectorstore: 
-
-```bash
-export DB_PASSWORD=""
+* Edit `start.sh` to change the DB_PASSWORD or any other reference/credentials changed by the dev env, as in this example:
+```
+export SPRING_AI_OPENAI_API_KEY=$OPENAI_API_KEY
+export DB_DSN="jdbc:oracle:thin:@localhost:1521/FREEPDB1"
+export DB_USERNAME=<DB_USER_NAME>
+export DB_PASSWORD=<DB_PASSWORD>
+export DISTANCE_TYPE=COSINE
+export OPENAI_CHAT_MODEL=gpt-4o-mini
+export OPENAI_EMBEDDING_MODEL=text-embedding-3-small
+export OLLAMA_CHAT_MODEL="llama3.1"
+export OLLAMA_EMBEDDING_MODEL=mxbai-embed-large
+export OLLAMA_BASE_URL="http://<OLLAMA_SERVER>:11434"
+export CONTEXT_INSTR=" You are an assistant for question-answering tasks. Use the retrieved Documents and history to answer the question as accurately and comprehensively as possible. Keep your answer grounded in the facts of the Documents, be concise, and reference the Documents where possible. If you don't know the answer, just say that you are sorry as you don't haven't enough information. "
+export TOP_K=4
+export VECTOR_STORE=TEXT_EMBEDDING_3_SMALL_8191_1639_COSINE
+export PROVIDER=openai
+mvn spring-boot:run -P openai
 ```
+
 * The `<VECTOR_STORE>` created in the Oracle AI Optimizer and Toolkit will be automatically converted in a `<VECTOR_STORE>_SPRINGAI` table, and it will store the same data. If already exists it will be used without modification.
 If you want to start from scratch, drop the table `<VECTOR_STORE>_SPRINGAI`, running in sql:
 
@@ -45,6 +59,7 @@ COMMIT;
 * This microservice will expose the following REST endpoints:
 
   * `http://localhost:9090/v1/chat/completions`: to use RAG via OpenAI REST API 
+  * `http://localhost:9090/v1/models`: return models behind the RAG via OpenAI REST API 
   * `http://localhost:9090/v1/service/llm` : to chat straight with the LLM used
   * `http://localhost:9090/v1/service/search/`: to search for document similar to the message provided
   * `http://localhost:9090/v1/service/store-chunks/`: to embedd and store a list of text chunks in the vectorstore
@@ -131,6 +146,37 @@ response will be a list of vector embeddings created:
 ]
 ```
 
+### Get model name
+Return the name of model used. It's useful to integrate ChatGUIs that require the model list before proceed.
+
+```
+curl http://localhost:9090/v1/models
+```
+
+## MCP RagTool
+The completion service is also available as an MCP server based on the **SSE** transport protocol.
+To test it:
+
+* Start as usual the microservice: 
+```shell
+./start.sh
+```
+
+* Start the **MCP inspector**:
+```shell
+export DANGEROUSLY_OMIT_AUTH=true
+npx @modelcontextprotocol/inspector  
+```
+
+* With a web browser open: http://127.0.0.1:6274
+
+* Configure:
+  * Transport Type: SSE
+  * URL: http://localhost:9090/sse
+  * set Request Timeout to: **200000**
+
+* Test a call to `getRag` Tool.
+
 
 ### Run in the Oracle Backend for Microservices and AI
 
@@ -262,4 +308,8 @@ it should return something like:
     }
   ]
 }
-```
+```
+
+{{% notice style="code" title="Documentation is Hard!" icon="circle-info" %}}
+More information coming soon... 25-June-2025
+{{% /notice %}}