Istedlal Server

MCP Server for Istedlal AI Agents - file metadata, vector search, workflow metrics access.

Requirements

• Python 3.10+
• See requirements.txt for 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 server
• venv/ – Create fresh on server or use Docker
• .env – Contains secrets; set separately on server
• __pycache__/ – Python cache, auto-generated
• data/ – 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

1. Build: docker build -t istedlal-mcp .
2. Run: docker run -p 8000:8000 -e DATABASE_URL=... -e MCP_BEARER_TOKEN=your-secret istedlal-mcp
3. Verify: curl http://localhost:8000/ (info page)
4. 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