使用说明
Istedlal MCP服务器
用于Istedlal AI代理的MCP服务器-文件元数据、矢量搜索、工作流指标访问。
需求
- Python 3.10+
- 看
requirements.txt对于依赖关系
设置
# 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)
跑
终端测试 （使用可流式传输的http以避免“无效的JSON:EOF”错误）：
# .env: MCP_TRANSPORT=streamable-http
python -m src.main
# Server at http://localhost:8000/mcp
游标/IDE集成 （stdio-游标生成进程，不要手动运行）：
# .env: MCP_TRANSPORT=stdio
# Add server to Cursor MCP settings; Cursor will start it automatically
工具
get_file_metadata-按ID获取文件的元数据（当VECTOR_PROVIDER=pgvector时为真实数据库）search_files-通过元数据过滤器搜索文件（pgvector时为真实数据库）semantic_search_files-文件嵌入的语义搜索（Ollama+pgvector）
MCP检验员测试
看 docs/MCP_INSPECTOR_GUIDE.md 获取完整的分步指南。
npx -y @modelcontextprotocol/inspector
生产
生产清单
| 项目 | 必填 | 备注 |
|---|---|---|
| Dockerfile | 是 | 构建容器映像 |
| .doccerignore | 是 | 排除venv、.env， __pycache__ |
| Production.env | 是 | 在服务器上设置（从不提交） |
| 端口8000 | 是 | MCP端点暴露 |
| PostgreSQL+pgvector | 第2阶段 | 文档元数据、文档嵌入（见data/vectordb_schema-documentation.pdf） |
| Ollama | 第2阶段 | 用于语义搜索查询嵌入 |
从部署中排除什么
.cursor/–仅游标IDE配置，服务器上不需要venv/–在服务器上创建新的或使用Docker.env-包含秘密；在服务器上单独设置__pycache__/–Python缓存，自动生成data/–仅参考文档，不包括运行时
生产环境变量
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（通过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"]
.doccerignore（创建以从构建中排除）
venv/
.env
.git/
.cursor/
__pycache__/
*.pyc
data/
docs/
scripts/
tests/
infra/
部署步骤
- 构建：
docker build -t istedlal-mcp . - 运行：
docker run -p 8000:8000 -e DATABASE_URL=... -e MCP_BEARER_TOKEN=your-secret istedlal-mcp - 验证：
curl http://localhost:8000/（信息页） - MCP端点：
http://your-server:8000/mcp
Kubernetes（可选）
- 使用部署+服务清单
infra/k8s/ - 公开服务（集群IP/节点端口/负载均衡器）
- 通过Secret设置DATABASE_URL
健康与监测
- 根
/返回带状态的JSON - MCP端点：
/mcp（仅适用于MCP客户） - 日志：设置LOGLEVEL=DEBUG进行故障排除
