Manages environment configuration for the MCP server, specifically handling USER_ID and CONTENT_SERVICE_URL variables.
Used as the web framework for potential future REST API functionality within the MCP server.
Used for development workflows to enforce code quality standards through Git hooks.
Provides data validation for the MCP server's request and response structures.
Powers the testing framework for the MCP server, including unit tests and coverage reporting.
Provides fast Python linting capabilities for the codebase.
Click on "Install Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@Content Server search for content about our quarterly marketing strategy"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
This is a Python implementation of the RAG (Retrieval-Augmented Generation) MCP (Model Context Protocol) server, equivalent to the Java version. It provides tools for managing organizational content through a content service API.
The server provides the following MCP tools:
listContentNames - List all content names from the organization's database, optionally filtered by name
searchOrganizationContents - Search through the organization's content database using semantic search
deleteOrganizationContent - Delete specific content from the organization's database
uploadContentFileAboutOrganization - Upload content files about the organization
uploadContentUrlAboutOrganization - Upload content URLs about the organization
Related MCP server: OrgFlow MCP
Install uv for fast Python package management:
# Install uv
curl -LsSf https://astral.sh/uv/install.sh | sh
# or
pip install uvThe fastest way to get started:
# Run tests
./test_uv.sh
# Start the server
./run_server_uv.shDependencies are automatically managed from pyproject.toml:
# Run directly (uv reads pyproject.toml automatically)
uv run mcp_server.py
# Or run tests
uv run test_server.py
# Install in development mode
uv sync
# Install with development dependencies
uv sync --devNo configuration files needed - dependencies declared inline:
# Run directly with inline dependencies
uv run \
--with mcp==1.0.0 \
--with fastapi==0.115.5 \
--with uvicorn==0.32.1 \
--with requests==2.32.3 \
--with python-multipart==0.0.17 \
--with pydantic==2.10.3 \
--with python-dotenv==1.0.1 \
mcp_server.py# Create and activate virtual environment
uv venv
source .venv/bin/activate
# Install dependencies
uv pip install mcp==1.0.0 fastapi==0.115.5 uvicorn==0.32.1 requests==2.32.3 python-multipart==0.0.17 pydantic==2.10.3 python-dotenv==1.0.1
# Run the server
python mcp_server.pyCopy the example environment file:
cp env.example .envEdit .env file with your configuration:
USER_ID=your_user_id_here
CONTENT_SERVICE_URL=http://localhost:8080./run_server_uv.shScript automatically detects pyproject.toml and uses it, falling back to inline dependencies
./run_server.sh# With pyproject.toml
uv run mcp_server.py
# Or with inline dependencies
uv run \
--with mcp==1.0.0 \
--with fastapi==0.115.5 \
--with uvicorn==0.32.1 \
--with requests==2.32.3 \
--with python-multipart==0.0.17 \
--with pydantic==2.10.3 \
--with python-dotenv==1.0.1 \
mcp_server.pyThe server will start and listen for MCP protocol messages via stdin/stdout.
USER_ID: The user ID to use for API calls (defaults to "invalid")
CONTENT_SERVICE_URL: The URL of the content service API (defaults to "http://localhost:8080")
./test_uv.sh
# or
uv run test_server.py # Uses pyproject.toml./run_server.sh # This will set up venv and install dependencies
source .venv/bin/activate && python test_server.py# Install all dependencies including dev tools
uv sync --dev
# This includes: pytest, black, ruff, mypy, pre-commit# Format code with black
uv run black .
# Lint with ruff
uv run ruff check .
# Type check with mypy
uv run mypy .# Run all tests
uv run pytest
# Run with coverage
uv run pytest --cov
# Run only unit tests
uv run pytest -m unitThe Python MCP server consists of three main components:
rag_service.py)Handles all HTTP API calls to the content service
Manages file uploads and URL submissions
Provides error handling and logging
rag_tools.py)Defines the MCP tools that are exposed to clients
Acts as a bridge between MCP tool calls and the RagService
Handles parameter validation and response formatting
mcp_server.py)Implements the MCP protocol using the Python MCP SDK
Handles tool registration and execution
Manages the server lifecycle and communication
{
"name": "listContentNames",
"description": "List all content names from the organization's database optionally filtered by name",
"inputSchema": {
"type": "object",
"properties": {
"name": {
"type": "string",
"description": "Optional name filter to search for specific content"
}
}
}
}{
"name": "searchOrganizationContents",
"description": "Search through the organization's content database using semantic search",
"inputSchema": {
"type": "object",
"properties": {
"query": {
"type": "string",
"description": "The search query"
}
},
"required": ["query"]
}
}{
"name": "deleteOrganizationContent",
"description": "Delete specific content from the organization's database",
"inputSchema": {
"type": "object",
"properties": {
"contentId": {
"type": "string",
"description": "The ID of the content to delete"
}
},
"required": ["contentId"]
}
}{
"name": "uploadContentFileAboutOrganization",
"description": "Upload content file about the organization",
"inputSchema": {
"type": "object",
"properties": {
"file": {
"type": "string",
"description": "The file content to upload"
},
"fileName": {
"type": "string",
"description": "The file name"
},
"role": {
"type": "string",
"description": "The roles of the user"
}
},
"required": ["file", "fileName"]
}
}{
"name": "uploadContentUrlAboutOrganization",
"description": "Upload content url about the organization",
"inputSchema": {
"type": "object",
"properties": {
"url": {
"type": "string",
"description": "The URL to upload"
},
"role": {
"type": "string",
"description": "The roles of the user"
}
},
"required": ["url"]
}
}mcp==1.0.0 - MCP Python SDK
fastapi==0.115.5 - Web framework (for potential future REST API)
uvicorn==0.32.1 - ASGI server
requests==2.32.3 - HTTP client library
python-multipart==0.0.17 - Multipart form data handling
pydantic==2.10.3 - Data validation
python-dotenv==1.0.1 - Environment variable management
pytest>=7.0.0 - Testing framework
pytest-asyncio>=0.21.0 - Async testing support
pytest-cov>=4.0.0 - Coverage reporting
black>=23.0.0 - Code formatting
ruff>=0.1.0 - Fast Python linter
mypy>=1.0.0 - Type checking
pre-commit>=3.0.0 - Git hooks
Dependencies are managed via pyproject.toml with uv for modern Python packaging
rag-mcp-py/
├── README.md # This documentation
├── pyproject.toml # Project configuration and dependencies
├── env.example # Environment configuration template
├── .env # Environment configuration (create from template)
├── .gitignore # Git ignore patterns
├── mcp_server.py # Main MCP server implementation
├── rag_service.py # HTTP service layer
├── rag_tools.py # MCP tools definitions
├── test_server.py # Test suite
├── run_server.sh # Traditional startup script (creates .venv)
├── run_server_uv.sh # uv-based startup script (recommended)
└── test_uv.sh # uv-based test scriptThis Python implementation mirrors the functionality of the Java MCP server:
Java Component | Python Equivalent | Description |
|
| Main server application |
|
| Tool definitions and handlers |
|
| Business logic and API calls |
The Python version maintains the same API contracts and tool schemas as the Java version, ensuring compatibility with existing MCP clients.
We use uv for package management because it's:
Fast: 10-100x faster than pip (installed 23 packages in 28ms!)
Reliable: Better dependency resolution
Modern: Built with Rust, designed for modern Python workflows
Flexible: Works with pyproject.toml, inline dependencies, or traditional approaches
Standards Compliant: Full support for PEP 621 and modern Python packaging
# Install uv
curl -LsSf https://astral.sh/uv/install.sh | sh
# Restart your shell or source the pathchmod +x *.shCheck if the content service is running on the configured URL
Verify environment variables in .env
Check Python version (requires Python 3.10+)
Dependencies are automatically managed by uv from pyproject.toml or inline declarations!
Delete specific content from the organization's database
| Name | Required | Description | Default |
|---|---|---|---|
| contentId | Yes | The ID of the content to delete |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of behavioral disclosure. It states the tool deletes content, implying a destructive mutation, but doesn't disclose critical traits like whether deletion is permanent or reversible, required permissions, rate limits, or error handling. This is a significant gap for a destructive tool with zero annotation coverage.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence that directly states the tool's action. It's front-loaded with the key verb 'Delete' and avoids unnecessary words. However, it could be slightly more informative without losing conciseness, such as specifying content type.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's destructive nature, no annotations, and no output schema, the description is incomplete. It lacks details on behavioral traits (e.g., permanence, auth needs), usage context, and return values. For a mutation tool with this complexity, the description should provide more guidance to compensate for missing structured data.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% description coverage, with 'contentId' clearly documented as 'The ID of the content to delete'. The description adds no additional meaning beyond this, such as format examples or sourcing guidance. With high schema coverage, the baseline is 3, as the schema does the heavy lifting.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states the action ('Delete') and target ('specific content from the organization's database'), which clarifies the basic purpose. However, it doesn't specify what type of content (e.g., files, records, metadata) or distinguish it from sibling tools like 'uploadContentFileAboutOrganization' that handle content creation. The purpose is clear but lacks specificity and differentiation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives. It doesn't mention prerequisites (e.g., content must exist), exclusions (e.g., cannot delete certain content types), or relationships to siblings like 'listContentNames' for identifying content to delete. Usage is implied by the action but without explicit context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List all content names from the organization's database optionally filtered by name
| Name | Required | Description | Default |
|---|---|---|---|
| name | No | Optional name filter to search for specific content |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of behavioral disclosure. It states it's a list operation, implying read-only behavior, but doesn't address key aspects like whether it's paginated, rate-limited, requires authentication, or what the return format is. For a tool with no annotations, this leaves significant gaps in understanding its behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence that front-loads the core purpose ('List all content names') and includes the optional filtering detail. There's no wasted text, making it highly concise and well-structured for quick comprehension.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no annotations, no output schema, and a simple parameter, the description is incomplete. It doesn't explain what 'content names' entail (e.g., file names, titles), how results are returned, or any limitations. For a list tool with siblings offering similar functionality, more context is needed to guide effective use.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema description coverage is 100%, with the single parameter 'name' documented as 'Optional name filter to search for specific content'. The description adds minimal value by restating this as 'optionally filtered by name', but doesn't provide additional context like wildcard support or case sensitivity. Baseline 3 is appropriate since the schema does the heavy lifting.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'List all content names from the organization's database optionally filtered by name.' It includes a specific verb ('List'), resource ('content names'), and scope ('organization's database'), which makes the purpose understandable. However, it doesn't explicitly differentiate from sibling tools like 'searchOrganizationContents', which might offer more advanced filtering or different output formats.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides minimal guidance by mentioning optional filtering by name, but it doesn't specify when to use this tool versus alternatives like 'searchOrganizationContents'. There's no mention of prerequisites, performance considerations, or exclusions, leaving the agent with little context for tool selection among siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search through the organization's content database using semantic search
| Name | Required | Description | Default |
|---|---|---|---|
| query | Yes | The search query |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It mentions 'semantic search' which adds some behavioral context beyond basic search, but doesn't disclose critical traits like whether this is read-only (likely, but not stated), what permissions are needed, rate limits, pagination behavior, or what the search covers (e.g., metadata, full text). For a search tool with zero annotation coverage, this is inadequate.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence that front-loads the core purpose. There's no wasted text, but it could be slightly more structured by explicitly mentioning the tool's scope or constraints.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no annotations, no output schema, and a simple input schema, the description is incomplete. It lacks information on behavioral traits (e.g., safety, performance), output format (what results look like), and usage context relative to siblings. For a search tool in an organization content system, this leaves significant gaps for an AI agent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% (the single parameter 'query' is documented in the schema as 'The search query'), so the baseline is 3. The description adds no additional meaning about the parameter beyond what the schema provides—it doesn't explain query format, length limits, or how semantic search interprets the query.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('search through') and resource ('organization's content database') with the method 'using semantic search'. It distinguishes from siblings like listContentNames (listing names only) and upload tools (adding content). However, it doesn't explicitly contrast with deleteOrganizationContent.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit guidance on when to use this tool versus alternatives is provided. The description implies searching content, but doesn't specify when to prefer this over listContentNames for browsing or when semantic search is appropriate versus other search methods. No exclusions or prerequisites are mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Upload content file about the organization
| Name | Required | Description | Default |
|---|---|---|---|
| file | Yes | The file content to upload | |
| fileName | Yes | The file name | |
| role | No | The roles of the user |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden but only states the action without behavioral details. It does not disclose permissions needed, effects on the system (e.g., overwriting), rate limits, or response format. This is inadequate for a mutation tool with zero annotation coverage.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence with no wasted words. However, it is under-specified rather than concise, as it lacks necessary context for a mutation tool.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a mutation tool with no annotations and no output schema, the description is incomplete. It does not cover behavioral aspects, usage context, or differences from siblings, leaving significant gaps for an AI agent to understand proper invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so parameters are documented in the schema. The description adds no meaning beyond the schema, such as explaining 'role' usage or file format constraints. Baseline 3 is appropriate as the schema handles parameter documentation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Upload content file about the organization' restates the tool name with minimal elaboration, making it tautological. It specifies the verb ('upload') and resource ('content file about the organization') but lacks detail on what this means operationally or how it differs from sibling tools like 'uploadContentUrlAboutOrganization'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives. It does not mention prerequisites, context for file uploads, or distinctions from sibling tools such as 'uploadContentUrlAboutOrganization' (for URLs) or 'listContentNames' (for listing).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Upload content url about the organization
| Name | Required | Description | Default |
|---|---|---|---|
| url | Yes | The URL to upload | |
| role | No | The roles of the user |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden but only states the action without behavioral details. It doesn't disclose permissions needed, rate limits, whether it's idempotent, or what happens on success/failure. 'Upload' suggests mutation, but no safety or side-effect information is provided.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence with no wasted words. It's front-loaded and appropriately sized for the tool's apparent complexity, making it easy to parse quickly.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a mutation tool with no annotations and no output schema, the description is incomplete. It lacks details on what 'content' means, how the upload integrates with the organization, or what the tool returns. Given the context, more information is needed for effective use.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so parameters 'url' and 'role' are documented in the schema. The description adds no meaning beyond the schema, as it doesn't explain parameter interactions or provide examples. Baseline 3 is appropriate since the schema handles documentation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Upload content url about the organization' states the action (upload) and resource (content url about organization), but it's vague about what 'content' entails and doesn't distinguish from sibling 'uploadContentFileAboutOrganization'. It provides a basic purpose but lacks specificity.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives like 'uploadContentFileAboutOrganization' or 'searchOrganizationContents'. The description implies uploading from a URL, but it doesn't specify contexts, prerequisites, or exclusions, leaving usage unclear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Most tools have distinct purposes: listing, searching, deleting, and two upload methods (file vs. URL). However, 'listContentNames' and 'searchOrganizationContents' could be confused as both retrieve content, though 'search' implies semantic filtering while 'list' is name-based. The two upload tools are clearly differentiated by input type.
Naming is inconsistent with mixed conventions: 'deleteOrganizationContent' uses camelCase, while 'listContentNames', 'searchOrganizationContents', and the upload tools use a mix of camelCase and descriptive phrases. There's no uniform verb_noun pattern; for example, 'uploadContentFileAboutOrganization' is overly verbose and deviates from simpler naming like 'uploadContentFile'.
With 5 tools, the count is well-scoped for a content management server. It covers core operations (list, search, delete, upload via file, upload via URL) without being overwhelming or too sparse, fitting typical server purposes efficiently.
The toolset covers basic CRUD operations: create (via upload tools), read (list and search), and delete, but lacks an update tool for modifying existing content. This gap could cause agent failures if content needs editing, though agents might work around it by deleting and re-uploading.
Unclaimed servers have limited discoverability.
If you are the server author, to access and configure the admin panel.
Manage translation projects, phrases and locales with secure organization-scoped tools and views.
Manage WeInc AI website builder orgs: projects, publishing, custom domains, and previews.
Create and publish one-pagers and boards for your organization. Upload images from the web, update…
Organization-scoped BrandPresence evidence and explicitly authorized product actions over MCP.
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/yogeshkulkarni553/rag-mcp-py'
If you have feedback or need assistance with the MCP directory API, please join our Discord server
