AI导哈

模型上下文协议服务器

一个HTTP友好的模型上下文协议（MCP）服务器，为MCP客户端提供JSON-RPC接口，并为管理提示、资源和工具提供版本化的REST API。

  • by NaziurRahman1312
  • Python
  • 本地部署
  • 更新于
在 GitHub 查看 NaziurRahman1312/mcp-server-101

使用说明

智能MCP服务器

一个HTTP-友好模型上下文协议（MCP）服务器，它为MCP客户端公开JSON-RPC，并提供一个版本化的REST API，用于管理提示、资源和工具。该实现遵循域、用例、基础设施和适配器之间的干净架构划分。持久性通过SQLAlchemy依赖于SQLite，而语义搜索则由FAISS+句子转换器嵌入提供支持。一切都是容器/Kubernetes就绪的，并附带了自动化测试。

🚀 亮点

  • 干净的架构布局（域/用例/适配器/基础设施）
  • FastAPI应用程序，带有与Cursor和其他MCP客户端兼容的手动JSON-RPC处理程序
  • 通过SQLAlchemy+Pydantic域模型实现SQLite持久化
  • FAISS矢量存储，用于对资源/工具进行语义搜索
  • SentenceTransformer嵌入（可配置模型）
  • Kubernetes为DB+FAISS索引提供持久存储
  • 演示脚本和基于pytest的API覆盖范围
  • 自动文档可在 /docs

📋 先决条件

  • Python 3.12+
  • 点

🛠️ 安装

cd /Users/mdnaziurrahman/Documents/mcp-server-101
python3.12 -m venv venv
source venv/bin/activate
pip install -r requirements.txt

1.为数据库添加种子

python scripts/seed_data.py

这将重置SQLite数据库+FAISS索引，并加载精心策划的提示/资源/工具。

2.运行服务器

python run_server.py

终点：

  • JSON-RPC MCP端点： POST http://127.0.0.1:8000/
  • REST API根： http://127.0.0.1:8000/api/v1
  • 文件： http://127.0.0.1:8000/docs
  • 健康： http://127.0.0.1:8000/health

📁 项目结构

mcp-server-101/
├── src/
│   └── mcp_server/
│       ├── __init__.py
│       ├── core/                # configuration helpers
│       ├── domain/              # domain models + repository interfaces
│       ├── usecases/            # application services
│       ├── infrastructure/      # SQLite + FAISS adapters
│       └── adapters/http/       # FastAPI app + schemas
├── scripts/
│   └── seed_data.py
├── deploy/                      # Kubernetes manifests
├── tests/                       # pytest API coverage
├── docs/
├── run_server.py
├── requirements.txt
└── README.md

⚙️ 配置

环境变量（默认值存在 core/config.py):

变量 描述 默认值
MCP_DATABASE_URL SQLAlchemy URL sqlite:///data/mcp.db
MCP_FAISS_INDEX_PATH FAISS索引文件的路径 data/faiss.index
MCP_EMBEDDING_MODEL_NAME 句子转换器模型 sentence-transformers/all-MiniLM-L6-v2
MCP_EMBEDDING_DIM 嵌入向量维度 384
MCP_FAISS_TOP_K 默认语义结果计数 5

🔌 API概述

MCP JSON-RPC(POST /)

支持的方法： initialize, notifications/initialized, resources/list, resources/read, prompts/list, prompts/get, tools/list, tools/call, ping.

REST管理API(/api/v1)

方法 路径 描述
GET /prompts 列表提示
GET /prompts/{id} 提取提示
POST /prompts 创建提示
PUT /prompts/{id} 更新提示
DELETE /prompts/{id} 删除提示
GET/POST/PUT/DELETE /resources, /tools 资源和工具的语义相同
GET `/search?q=...&target=all prompt
GET /health 健康探头
GET /docs FastAPI swagg-docs

快速cURL片段

# Create a prompt
curl -X POST http://localhost:8000/api/v1/prompts \
  -H "Content-Type: application/json" \
  -d '{"name":"My Prompt","role":"system","content":"Hi","tags":["demo"]}'

# Semantic search
curl "http://localhost:8000/api/v1/search?q=vector+database"

# MCP initialize
curl -X POST http://localhost:8000/ \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{}}'

🧰 内置Meta MCP工具

MCP tools/list 响应总是包含一组元工具，因此Cursor（或任何MCP客户端）可以在没有定制REST调用的情况下管理数据：

  • meta.createPrompt / meta.updatePrompt
  • meta.createResource / meta.updateResource
  • meta.createTool / meta.updateTool
  • meta.searchResources / meta.searchTools （FAISS支持的语义搜索）

用标准调用它们 tools/call RPC并将记录的JSON模式传递给 arguments.Responses以JSON格式返回受影响的对象（或搜索结果）。

🔍 与光标一起使用

创建或更新 ~/.cursor/mcp.json:

{
  "mcpServers": {
    "dev-mcp": {
      "url": "http://localhost:8000",
      "type": "http",
      "enabled": true
    }
  }
}

您的MCP服务器将显示为 dev-mcp 可以访问提示/资源/工具以及语义搜索。

🧪 测试

pytest

互动演示

python scripts/demo_management_api.py

该脚本执行健康检查、CRUD、语义搜索和JSON-RPC发现流程。

☁️ Kubernetes部署

kubectl apply -f deploy/pvc.yaml
kubectl apply -f deploy/deployment.yaml
kubectl apply -f deploy/service.yaml

该部署安装了一个PVC /app/data 因此SQLite和FAISS索引在pod重启时都会持续存在。更新 image 标签指向您已发布的容器。

📦 依赖项

  • fastapi, uvicorn[standard]
  • pydantic, pydantic-settings
  • sqlalchemy
  • sentence-transformers, faiss-cpu
  • mcp[cli]
  • pytest 用于测试

看 requirements.txt 查看完整列表。

📄 许可证

MIT许可证-可根据需要自由使用和修改。

🤝 贡献

这是一个个人/学习项目。请随意分叉和定制！

内置于❤️ 使用官方的MCP Python SDK。

相关 MCP