feat: make mcptool description configurable (#55)

This pull request introduces significant updates to the MCP server,
including the addition of an extensible docstring system, restructuring
of file paths, and enhancements to configuration and testing setups.
These changes aim to improve maintainability, scalability, and developer
experience.

### Enhancements to MCP Server Functionality

* Added a new extensible docstring system (`DocstringTemplateSystem`)
that uses Jinja2 templates to dynamically generate method docstrings
based on configuration. This includes the `extensible_docstring`
decorator and `setup_extensible_docstrings` utility for seamless
integration. (`services/mcp-server/src/docstring_system.py`,
`services/mcp-server/src/rag_mcp_server.py`)
[[1]](diffhunk://#diff-0dcdbe141882267f8d9fc27375b94ded2088f5592b35afc540d753db0a4ae571R1-R223)
[[2]](diffhunk://#diff-c8d76fe95b7721b6d9cfcedcef267b70303d5ef731160d3c6d08e5883a4a670dR14-R15)
[[3]](diffhunk://#diff-c8d76fe95b7721b6d9cfcedcef267b70303d5ef731160d3c6d08e5883a4a670dR28-L80)
* Updated the `MCPSettings` class to include detailed configuration
options for `chat_simple` and `chat_with_history` methods, such as
descriptions, parameter details, return types, and examples. These
settings are used by the new docstring system.
(`services/mcp-server/src/settings/mcp_settings.py`)
[[1]](diffhunk://#diff-43115db49b21446e10cae3c5571cc8090a4e0565ea3d7871413d29865140533bL1-R5)
[[2]](diffhunk://#diff-43115db49b21446e10cae3c5571cc8090a4e0565ea3d7871413d29865140533bR34-R66)

### Restructuring and Path Updates

* Refactored file paths in `.vscode/settings.json` and `conftest.py` to
align with the new directory structure under `services/`. This includes
adding `mcp-server/src` and updating imports for backend services.
(`.vscode/settings.json`, `conftest.py`)
[[1]](diffhunk://#diff-a5de3e5871ffcc383a2294845bd3df25d3eeff6c29ad46e3a396577c413bf357L9-R12)
[[2]](diffhunk://#diff-a31c7ed5d35f5ed8233994868c54d625b18e6bacb6794344c4531e62bd9dde59L7-R19)

### Infrastructure and Configuration Updates

* Enhanced the Helm chart configuration (`configmap.yaml`,
`values.yaml`) to support additional metadata for the MCP server, such
as host, descriptions, and examples for chat tools. These changes enable
better customization and documentation.
(`infrastructure/rag/templates/backend/configmap.yaml`,
`infrastructure/rag/values.yaml`)
[[1]](diffhunk://#diff-121c65fa1a9269554fc3a0d7774e34f409e3ce275d2a6c375552eee780ea6ea1L143-R152)
[[2]](diffhunk://#diff-673dd2d3d4e66a8fd4e45f9c1c9900711313f946bf8b6a89e96c954988fc14f3R23-R42)

### Testing and Development Environment Improvements

* Added pytest configuration to `pyproject.toml` in `mcp-server`,
including markers for test categorization (e.g., `unit`, `integration`)
and additional pytest options. (`services/mcp-server/pyproject.toml`)
* Updated `testpaths` in `libs/rag-core-api/pyproject.toml` to use a
list format for consistency with other configurations.
(`libs/rag-core-api/pyproject.toml`)

### Dependency Updates

* Introduced `jinja2` as a new dependency in
`services/mcp-server/pyproject.toml` to support the docstring templating
system. (`services/mcp-server/pyproject.toml`)

---------

Co-authored-by: Andreas Klos <[email protected]>

Author: a-klos

.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.