feat: make mcptool description configurable

.vscode/settings.json

@@ -6,9 +6,10 @@
         "./libs/rag-core-api/src",
         "./libs/rag-core-lib/src",
         "./libs/extractor-api-lib/src",
-        "./admin-backend",
-        "./rag-backend",
-        "./document-extractor"
+        "./services/mcp-server/src",
+        "./services/admin-backend",
+        "./services/rag-backend",
+        "./services/document-extractor"
     ],
     "[yaml]": {
         "editor.tabSize": 2,

README.md

@@ -78,6 +78,27 @@ The MCP server runs as a sidecar container alongside the main RAG backend and ex
 - `chat_simple`: Basic question-answering without conversation history
 - `chat_with_history`: Advanced chat interface with conversation history and returns structured responses with `answer`, `finish_reason`, and `citations`.
 
+##### Configuring Tool Documentation
+
+The MCP server supports customizable documentation for its tools through environment variables. This allows you to customize the descriptions, parameter explanations, and examples shown to MCP clients. All documentation configuration uses the `MCP_` prefix and can be configured with the [values.yaml](infrastructure/rag/values.yaml). The following configuration options exist:
+
+**For `chat_simple` tool:**
+
+- `MCP_CHAT_SIMPLE_DESCRIPTION`: Main description of the tool
+- `MCP_CHAT_SIMPLE_PARAMETER_DESCRIPTIONS`: JSON object mapping parameter names to descriptions
+- `MCP_CHAT_SIMPLE_RETURNS`: Description of the return value
+- `MCP_CHAT_SIMPLE_NOTES`: Additional notes about the tool
+- `MCP_CHAT_SIMPLE_EXAMPLES`: Usage examples
+
+**For `chat_with_history` tool:**
+
+- `MCP_CHAT_WITH_HISTORY_DESCRIPTION`: Main description of the tool
+- `MCP_CHAT_WITH_HISTORY_PARAMETER_DESCRIPTIONS`: JSON object mapping parameter names to descriptions
+- `MCP_CHAT_WITH_HISTORY_RETURNS`: Description of the return value
+- `MCP_CHAT_WITH_HISTORY_NOTES`: Additional notes about the tool
+- `MCP_CHAT_WITH_HISTORY_EXAMPLES`: Usage examples
+
+
 For further information on configuration and usage, please consult the [MCP Server README](./services/mcp-server/README.md).
 
 #### 1.1.5 Frontend

conftest.py

@@ -4,12 +4,16 @@
 
 # Add project root and specific directories to Python path
 project_root = Path(__file__).parent
-sys.path.insert(0, str(project_root))
-sys.path.insert(0, str(project_root / "admin-backend"))
-sys.path.insert(0, str(project_root / "rag-backend"))
-sys.path.insert(0, str(project_root / "document-extractor"))
+
+# Add services src directories to Python path
+services_root = project_root / "services"
+for service in ["admin-backend", "rag-backend", "document-extractor", "mcp-server"]:
+    service_src = services_root / service / "src"
+    if service_src.exists():
+        sys.path.insert(0, str(service_src))
 
 # point at each rag-core library's src folder so their packages (admin_api_lib, rag_core_api, etc.) are importable
 lib_root = project_root / "libs"
 for lib in ["admin-api-lib", "rag-core-api", "rag-core-lib", "extractor-api-lib"]:
     sys.path.insert(0, str(lib_root / lib / "src"))
+    sys.path.insert(0, str(lib_root / lib / "tests"))

infrastructure/rag/templates/backend/configmap.yaml

@@ -140,7 +140,15 @@ metadata:
   name: {{ template "configmap.mcp" . }}
 data:
   MCP_PORT: {{ .Values.backend.mcp.port | quote }}
-  MCP_TOOL_NAME: {{ .Values.backend.mcp.toolName }}
-  MCP_TOOL_DESCRIPTION: {{ .Values.backend.mcp.toolDescription }}
-  MCP_NAME: {{  .Values.backend.mcp.name }}
----
+  MCP_HOST: {{ .Values.backend.mcp.host | quote }}
+  MCP_NAME: {{ .Values.backend.mcp.name | quote }}
+  MCP_CHAT_SIMPLE_DESCRIPTION: {{ .Values.backend.mcp.chatSimpleDescription | quote }}
+  MCP_CHAT_SIMPLE_PARAMETER_DESCRIPTIONS: {{ .Values.backend.mcp.chatSimpleParameterDescriptions | toJson | quote }}
+  MCP_CHAT_SIMPLE_RETURNS: {{ .Values.backend.mcp.chatSimpleReturns | quote }}
+  MCP_CHAT_SIMPLE_NOTES: {{ .Values.backend.mcp.chatSimpleNotes | quote }}
+  MCP_CHAT_SIMPLE_EXAMPLES: {{ .Values.backend.mcp.chatSimpleExamples | quote }}
+  MCP_CHAT_WITH_HISTORY_DESCRIPTION: {{ .Values.backend.mcp.chatWithHistoryDescription | quote }}
+  MCP_CHAT_WITH_HISTORY_PARAMETER_DESCRIPTIONS: {{ .Values.backend.mcp.chatWithHistoryParameterDescriptions | toJson | quote }}
+  MCP_CHAT_WITH_HISTORY_RETURNS: {{ .Values.backend.mcp.chatWithHistoryReturns | quote }}
+  MCP_CHAT_WITH_HISTORY_NOTES: {{ .Values.backend.mcp.chatWithHistoryNotes | quote }}
+  MCP_CHAT_WITH_HISTORY_EXAMPLES: {{ .Values.backend.mcp.chatWithHistoryExamples | quote }}

infrastructure/rag/values.yaml

@@ -20,6 +20,53 @@ backend:
     name: "mcp"
     port: "8000"
     host: "0.0.0.0"
+
+    # Chat simple tool configuration
+    # The following configuration for the chat_simple tool will render as follows:
+    # """Send a message to the RAG system and get a simple text response.
+
+    # This is the simplest way to interact with the RAG system - just provide a message and get back the answer as plain text.
+    #
+    # Parameters
+    # ----------
+    # session_id : str
+    #     Unique identifier for the chat session.
+    # message : str
+    #     The message/question to ask the RAG system.
+    #
+    # Returns
+    # -------
+    # str
+    #     The answer from the RAG system as plain text.
+    # """
+    chatSimpleDescription: "Send a message to the RAG system and get a simple text response.\n\nThis is the simplest way to interact with the RAG system - just provide a message and get back the answer as plain text."
+    chatSimpleParameterDescriptions:
+      session_id: "Unique identifier for the chat session."
+      message: "The message/question to ask the RAG system."
+    chatSimpleReturns: "The answer from the RAG system as plain text."
+    chatSimpleNotes: ""
+    # If you add a Value to chatSimpleNotes e.g. "This tool is best for simple questions that don't require conversation context."
+    # it will render to:
+    # Notes
+    # -----
+    # This tool is best for simple questions that don't require conversation context.
+    chatSimpleExamples: ""
+    # If you add a Value to chatSimpleExamples e.g. "chat_simple(session_id='my-session', message='What is the main topic of the document?')"
+    # it will render to:
+    # Examples
+    # --------
+    # chat_simple(session_id='my-session', message='What is the main topic of the document?')
+
+    # Chat with history tool configuration
+    chatWithHistoryDescription: "Send a message with conversation history and get structured response.\n\nProvide conversation history as a simple list of dictionaries.\nEach history item should have 'role' (either 'user' or 'assistant') and 'message' keys."
+    chatWithHistoryParameterDescriptions:
+      session_id: "Unique identifier for the chat session."
+      message: "The current message/question to ask."
+      history: "Previous conversation history. Each item should be:\n    {\"role\": \"user\" or \"assistant\", \"message\": \"the message text\"}"
+    chatWithHistoryReturns: "Response containing:\n    - answer: The response text\n    - finish_reason: Why the response ended\n    - citations: List of source documents used (simplified)"
+    chatWithHistoryNotes: ""
+    chatWithHistoryExamples: ""
+
     image:
       repository: ghcr.io/stackitcloud/rag-template
       name: rag-mcp

libs/rag-core-api/pyproject.toml

@@ -122,5 +122,5 @@ max-line-length = 120
 log_cli = true
 log_cli_level = "DEBUG"
 pythonpath = ["src", "tests"]
-testpaths = "tests"
+testpaths = ["tests"]
 

services/mcp-server/README.md

@@ -78,6 +78,122 @@ The server supports configuration through environment variables with the followi
 
 - `BACKEND_BASE_PATH`: RAG backend URL (default: `http://127.0.0.1:8080`)
 
+### Tool Documentation Configuration
+
+The MCP server supports customizable documentation for its tools through environment variables. This allows you to customize the descriptions, parameter explanations, and examples shown to MCP clients.
+
+#### Chat Simple Tool Documentation
+
+- `MCP_CHAT_SIMPLE_DESCRIPTION`: Main description of the tool
+- `MCP_CHAT_SIMPLE_PARAMETER_DESCRIPTIONS`: JSON object mapping parameter names to descriptions
+- `MCP_CHAT_SIMPLE_RETURNS`: Description of the return value
+- `MCP_CHAT_SIMPLE_NOTES`: Additional notes about the tool
+- `MCP_CHAT_SIMPLE_EXAMPLES`: Usage examples
+
+#### Chat With History Tool Documentation
+
+- `MCP_CHAT_WITH_HISTORY_DESCRIPTION`: Main description of the tool
+- `MCP_CHAT_WITH_HISTORY_PARAMETER_DESCRIPTIONS`: JSON object mapping parameter names to descriptions
+- `MCP_CHAT_WITH_HISTORY_RETURNS`: Description of the return value
+- `MCP_CHAT_WITH_HISTORY_NOTES`: Additional notes about the tool
+- `MCP_CHAT_WITH_HISTORY_EXAMPLES`: Usage examples
+
+#### Example Configuration
+
+```env
+# Custom tool descriptions
+MCP_CHAT_SIMPLE_DESCRIPTION="Ask questions about your documents and get instant answers."
+MCP_CHAT_SIMPLE_EXAMPLES="chat_simple(session_id='my-session', message='What is the main topic of the document?')"
+
+# Custom parameter descriptions (JSON format)
+MCP_CHAT_SIMPLE_PARAMETER_DESCRIPTIONS='{"session_id": "A unique session identifier for your conversation", "message": "Your question about the documents"}'
+
+# Custom return description
+MCP_CHAT_SIMPLE_RETURNS="A plain text answer based on your document content"
+
+# Notes about usage
+MCP_CHAT_SIMPLE_NOTES="This tool is best for simple questions that don't require conversation context."
+```
+
+#### Template Rendering
+
+The MCP server uses Jinja2 templates to generate tool documentation in **numpy docstring format**. When the environment variables are set, they are rendered into a structured docstring that MCP clients can parse and display.
+
+**Example of rendered docstring:**
+
+Given the configuration above, the `chat_simple` tool's docstring would be rendered as:
+
+```python
+def chat_simple(session_id: str, message: str) -> str:
+    """Ask questions about your documents and get instant answers.
+
+    Parameters
+    ----------
+    session_id : str
+        A unique session identifier for your conversation
+    message : str
+        Your question about the documents
+
+    Returns
+    -------
+    str
+        A plain text answer based on your document content
+
+    Notes
+    -----
+    This tool is best for simple questions that don't require conversation context.
+
+    Examples
+    --------
+    chat_simple(session_id='my-session', message='What is the main topic of the document?')
+    """
+```
+
+This numpy-style docstring format ensures compatibility with documentation tools and provides clear, structured information to MCP clients about how to use each tool.
+
+### Helm Chart Configuration
+
+For production deployments, the MCP server documentation can be configured through the Helm chart's `values.yaml` file. This provides a structured way to manage tool documentation across different environments.
+
+The MCP configuration is located under `backend.mcp` in the [values.yaml](../../infrastructure/rag/values.yaml) file:
+
+```yaml
+backend:
+  mcp:
+    # Basic MCP server settings
+    name: "mcp"
+    port: "8000"
+    host: "0.0.0.0"
+
+    # Chat simple tool configuration
+    chatSimpleDescription: "Send a message to the RAG system and get a simple text response.\n\nThis is the simplest way to interact with the RAG system - just provide a message and get back the answer as plain text."
+    chatSimpleParameterDescriptions:
+      session_id: "Unique identifier for the chat session."
+      message: "The message/question to ask the RAG system."
+    chatSimpleReturns: "The answer from the RAG system as plain text."
+    chatSimpleNotes: ""
+    chatSimpleExamples: ""
+
+    # Chat with history tool configuration
+    chatWithHistoryDescription: "Send a message with conversation history and get structured response.\n\nProvide conversation history as a simple list of dictionaries.\nEach history item should have 'role' (either 'user' or 'assistant') and 'message' keys."
+    chatWithHistoryParameterDescriptions:
+      session_id: "Unique identifier for the chat session."
+      message: "The current message/question to ask."
+      history: "Previous conversation history. Each item should be:\n    {\"role\": \"user\" or \"assistant\", \"message\": \"the message text\"}"
+    chatWithHistoryReturns: "Response containing:\n    - answer: The response text\n    - finish_reason: Why the response ended\n    - citations: List of source documents used (simplified)"
+    chatWithHistoryNotes: ""
+    chatWithHistoryExamples: ""
+```
+
+These values are automatically converted to the appropriate environment variables (with `MCP_` prefix) when the Helm chart is deployed. The `chatSimpleParameterDescriptions` and `chatWithHistoryParameterDescriptions` dictionaries are automatically converted to JSON format for consumption by the MCP server.
+
+This approach allows you to:
+
+- Manage documentation consistently across environments
+- Version control your tool documentation
+- Use different documentation for different deployments (dev, staging, production)
+- Leverage Helm's templating features for dynamic documentation
+
 ## Deployment
 
 The MCP server is designed to be deployed alongside the main RAG backend as a sidecar container. A detailed explanation of the deployment can be found in the [main README](../README.md) and the [infrastructure README](../rag-infrastructure/README.md) of the project.