initial commit

Author: Coolgiserz

.cursorrules

@@ -0,0 +1,74 @@
+
+
+# Python (FastAPI)
+
+# Python (FastAPI) - Scalable API Development
+
+You are an expert in Python, FastAPI, and scalable API development.
+
+## Key Principles
+
+- Write concise, technical responses with accurate Python examples.
+- Use functional, declarative programming; avoid classes where possible.
+- Prefer iteration and modularization over code duplication.
+- Use descriptive variable names with auxiliary verbs (e.g., `is_active`, `has_permission`).
+- Use lowercase with underscores for directories and files (e.g., `routers/user_routes.py`).
+- Favor named exports for routes and utility functions.
+- Use the **Receive an Object, Return an Object (RORO)** pattern.
+
+## Python/FastAPI
+
+- Use `def` for pure functions and `async def` for asynchronous operations.
+- Use type hints for all function signatures. Prefer Pydantic models over raw dictionaries for input validation.
+- File structure: exported router, sub-routes, utilities, static content, types (models, schemas).
+- Avoid unnecessary curly braces in conditional statements.
+- For single-line statements in conditionals, omit curly braces.
+- Use concise, one-line syntax for simple conditional statements (e.g., `if condition: do_something()`).
+
+## Error Handling and Validation
+
+- Prioritize error handling and edge cases:
+  - Handle errors and edge cases at the beginning of functions.
+  - Use early returns for error conditions to avoid deeply nested `if` statements.
+  - Place the happy path last in the function for improved readability.
+  - Avoid unnecessary `else` statements; use the `if-return` pattern instead.
+  - Use guard clauses to handle preconditions and invalid states early.
+  - Implement proper error logging and user-friendly error messages.
+  - Use custom error types or error factories for consistent error handling.
+
+## Dependencies
+
+- **FastAPI**
+- **Pydantic v2**
+- Async database libraries like `asyncpg` or `aiomysql`
+- **SQLAlchemy 2.0** (if using ORM features)
+
+## FastAPI-Specific Guidelines
+
+- Use functional components (plain functions) and Pydantic models for input validation and response schemas.
+- Use declarative route definitions with clear return type annotations.
+- Use `def` for synchronous operations and `async def` for asynchronous ones.
+- Minimize `@app.on_event("startup")` and `@app.on_event("shutdown")`; prefer lifespan context managers for managing startup and shutdown events.
+- Use middleware for logging, error monitoring, and performance optimization.
+- Optimize for performance using async functions for I/O-bound tasks, caching strategies, and lazy loading.
+- Use `HTTPException` for expected errors and model them as specific HTTP responses.
+- Use middleware for handling unexpected errors, logging, and error monitoring.
+- Use Pydantic's `BaseModel` for consistent input/output validation and response schemas.
+
+## Performance Optimization
+
+- Minimize blocking I/O operations; use asynchronous operations for all database calls and external API requests.
+- Implement caching for static and frequently accessed data using tools like Redis or in-memory stores.
+- Optimize data serialization and deserialization with Pydantic.
+- Use lazy loading techniques for large datasets and substantial API responses.
+
+## Key Conventions
+
+1. Rely on FastAPI’s dependency injection system for managing state and shared resources.
+2. Prioritize API performance metrics (response time, latency, throughput).
+3. Limit blocking operations in routes:
+   - Favor asynchronous and non-blocking flows.
+   - Use dedicated async functions for database and external API operations.
+   - Structure routes and dependencies clearly to optimize readability and maintainability.
+
+Refer to [FastAPI documentation](https://fastapi.tiangolo.com/) for **Data Models**, **Path Operations**, and **Middleware** for best practices.

.dockerignore

@@ -0,0 +1,31 @@
+# Python
+__pycache__/
+*.pyc
+*.pyo
+*.pyd
+*.pycache__/
+*.pytest_cache/
+*.coverage
+.coverage.*
+.cache
+.pytest_cache/
+*.egg-info/
+.eggs/
+dist/
+build/
+
+.venv/
+env/
+venv/
+
+*.log
+*.tmp
+*.bak
+
+# Git
+.git/
+.gitignore
+
+# Docker
+Dockerfile
+docker-compose.yml

.gitignore

@@ -0,0 +1,19 @@
+# Python-generated files
+__pycache__/
+*.py[oc]
+build/
+dist/
+wheels/
+*.egg-info
+
+# Virtual environments
+.venv
+.env
+
+# IDE
+.idea/
+.vscode/
+# Logs
+*.log
+*.out
+.pytest_cache/

.python-version

@@ -0,0 +1 @@
+3.12

Dockerfile

@@ -0,0 +1,27 @@
+# 使用Python 3.12 精简版镜像
+FROM swr.cn-north-4.myhuaweicloud.com/ddn-k8s/ghcr.io/astral-sh/uv:python3.12-bookworm-slim
+# 设置工作目录
+WORKDIR /app
+
+# 重写 apt 源为 USTC 镜像并安装 curl
+RUN echo "deb http://mirrors.ustc.edu.cn/debian bookworm main contrib non-free" > /etc/apt/sources.list \
+    && echo "deb http://mirrors.ustc.edu.cn/debian bookworm-updates main contrib non-free" >> /etc/apt/sources.list \
+    && echo "deb http://mirrors.ustc.edu.cn/debian-security bookworm-security main contrib non-free" >> /etc/apt/sources.list \
+    && apt-get update \
+    && apt-get install -y --no-install-recommends curl \
+    && rm -rf /var/lib/apt/lists/*
+
+COPY pyproject.toml uv.lock /app
+
+ENV UV_PYPI_INDEX_URL=https://pypi.tuna.tsinghua.edu.cn/simple
+# 安装 Python 依赖
+# 优先使用 uv（如有 uv.lock），否则用 pip 安装 requirements.txt
+RUN pip install -i https://mirrors.aliyun.com/pypi/simple uv  && uv sync
+
+# 复制项目文件到容器
+COPY ./src/ /app
+# 暴露服务端口
+EXPOSE 8000
+
+# 启动 MCP Server
+CMD ["/app/.venv/bin/uvicorn", "main:app", "--host", "0.0.0.0", "--port", "8000"]

Makefile

@@ -0,0 +1,60 @@
+# Makefile for Customized ElasticSearch MCP Server
+
+# 镜像名称和标签
+IMAGE_NAME ?= customized-elasticsearch-mcp-server
+TAG ?= latest
+
+.PHONY: help init sync dev test lint format build docker-build docker-up docker-down docker-logs clean
+
+help:
+	@echo "Usage:"
+	@echo "  make init         初始化项目依赖 (uv init)"
+	@echo "  make sync         同步依赖 (uv sync)"
+	@echo "  make dev          启动开发服务器 (uvicorn 热重载)"
+	@echo "  make test         运行单元测试"
+	@echo "  make lint         代码检查 (flake8)"
+	@echo "  make format       代码格式化 (isort & black)"
+	@echo "  make build        本地构建 Docker 镜像"
+	@echo "  make docker-build 使用 docker-compose 构建镜像"
+	@echo "  make docker-up    使用 docker-compose 启动服务"
+	@echo "  make docker-down  使用 docker-compose 停止服务"
+	@echo "  make docker-logs  查看服务日志"
+	@echo "  make clean        清理 Python 缓存和临时文件"
+
+init:
+	uv init
+
+sync:
+	uv sync
+
+dev:
+	uv run uvicorn src.news_mcp_server.app:app --reload --host 0.0.0.0 --port 9009
+
+test:
+	uv run pytest --maxfail=1 --disable-warnings -q
+
+lint:
+	uv run flake8 src tests
+
+format:
+	uv run isort .
+	uv run black .
+
+build:
+	docker build -t $(IMAGE_NAME):$(TAG) .
+
+docker-build:
+	docker compose build
+
+docker-up:
+	docker compose up -d
+
+docker-down:
+	docker compose down
+
+docker-logs:
+	docker compose logs -f
+
+clean:
+	@find . -type f -name "*.py[co]" -delete || true
+	@find . -type d -name "__pycache__" -exec rm -rf {} + || true