README.md
MCP Server for Istedlal AI Agents providing file metadata and vector search.
Istedlal MCP Server
MCP Server for Istedlal AI Agents - file metadata, vector search, workflow metrics access.
Requirements
- Python 3.10+
- See
requirements.txtfor dependencies
Setup
# Create virtual environment
python -m venv venv
venv\Scripts\activate # Windows
# Install dependencies
pip install -r requirements.txt
# Create .env with required variables (see docs/ENV_SETUP.md)
Run
Terminal testing (use streamable-http to avoid "Invalid JSON: EOF" errors):
# .env: MCP_TRANSPORT=streamable-http
python -m src.main
# Server at http://localhost:8000/mcp
Cursor/IDE integration (stdio - Cursor spawns the process, don't run manually):
# .env: MCP_TRANSPORT=stdio
# Add server to Cursor MCP settings; Cursor will start it automatically
Tools
get_file_metadata- Fetch metadata for a file by ID (real DB when VECTOR_PROVIDER=pgvector)search_files- Search files by metadata filters (real DB when pgvector)semantic_search_files- Semantic search over file embeddings (Ollama + pgvector)
Testing with MCP Inspector
See docs/MCP_INSPECTOR_GUIDE.md for the complete step-by-step guide.
npx -y @modelcontextprotocol/inspector
Production
Production Checklist
| Item | Required | Notes |
|---|---|---|
| Dockerfile | Yes | Build container image |
| .dockerignore | Yes | Exclude venv, .env, pycache |
| Production .env | Yes | Set on server (never commit) |
| Port 8000 | Yes | Expose for MCP endpoint |
| PostgreSQL + pgvector | Phase 2 | document_metadata, document_embeddings (see data/vectordb_schema_documentation.pdf) |
| Ollama | Phase 2 | For semantic search query embeddings |
What to Exclude from Deployment
.cursor/– Cursor IDE config only, not needed on servervenv/– Create fresh on server or use Docker.env– Contains secrets; set separately on server__pycache__/– Python cache, auto-generateddata/– Reference docs only, not runtime
Production Environment Variables
MCP_TRANSPORT=streamable-http
HTTP_HOST=0.0.0.0
HTTP_PORT=8000
DATABASE_URL=postgresql://user:password@db-host:5432/dbname
VECTOR_PROVIDER=pgvector # mock | pgvector | chromadb
OLLAMA_URL=https://your-ollama:11433
OLLAMA_EMBEDDING_MODEL=llama3.2
OLLAMA_USERNAME= # if Basic Auth required
OLLAMA_PASSWORD=
LOG_LEVEL=INFO
MCP_BEARER_TOKEN=your-secret-token # Required – Bearer token auth for /mcp
Dockerfile (Create if Deploying via Docker)
FROM python:3.12-slim
WORKDIR /app
COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt
COPY src/ ./src/
ENV MCP_TRANSPORT=streamable-http
ENV PYTHONUNBUFFERED=1
EXPOSE 8000
CMD ["python", "-m", "src.main"]
.dockerignore (Create to Exclude from Build)
venv/
.env
.git/
.cursor/
__pycache__/
*.pyc
data/
docs/
scripts/
tests/
infra/
Deployment Steps
- Build:
docker build -t istedlal-mcp . - Run:
docker run -p 8000:8000 -e DATABASE_URL=... -e MCP_BEARER_TOKEN=your-secret istedlal-mcp - Verify:
curl http://localhost:8000/(info page) - MCP Endpoint:
http://your-server:8000/mcp
Kubernetes (Optional)
- Use Deployment + Service manifests in
infra/k8s/ - Expose Service (ClusterIP/NodePort/LoadBalancer)
- Set DATABASE_URL via Secret
Health & Monitoring
- Root
/returns JSON with status - MCP endpoint:
/mcp(for MCP clients only) - Logs: Set LOG_LEVEL=DEBUG for troubleshooting
Tools (3)
get_file_metadataFetch metadata for a file by ID.search_filesSearch files by metadata filters.semantic_search_filesSemantic search over file embeddings using Ollama and pgvector.Environment Variables
MCP_TRANSPORTrequiredTransport protocol (stdio or streamable-http)DATABASE_URLrequiredPostgreSQL connection stringVECTOR_PROVIDERVector database provider (mock, pgvector, or chromadb)MCP_BEARER_TOKENrequiredBearer token for /mcp endpoint authenticationConfiguration
claude_desktop_config.json
{"mcpServers": {"istedlal": {"command": "python", "args": ["-m", "src.main"], "env": {"MCP_TRANSPORT": "stdio", "DATABASE_URL": "postgresql://user:password@localhost:5432/dbname"}}}}Try it
→Find the metadata for the file with ID 12345.
→Search for all files created in the last week that contain the word 'project'.
→Perform a semantic search for documents related to 'Q4 financial strategy' using the vector database.
→List all files that match the metadata filter for 'author: John Doe'.