mcp-server✓ تایید شده

محتوای SKILL.md

---
name: mcp-server
description: This skill should be used when setting up a stateless MCP (Model Context Protocol) server in FastAPI using the Official MCP SDK with 5 task management tools that interact with SQLModel database.
---

# MCP Server Setup Skill

This skill provides guidance for setting up a stateless MCP server using the Official MCP SDK in FastAPI.

## Purpose

Create a stateless MCP server that provides 5 task management tools (add_task, list_tasks, complete_task, delete_task, update_task) with proper user isolation, database integration, and error handling.

## When to Use

Use this skill when:
- Setting up a new MCP server for chatbot integration
- Adding MCP tools for task management functionality
- Creating MCP server infrastructure with database integration
- Implementing tool chaining and error handling for MCP

## Capabilities

- **Stateless Design**: Each request independent, no server-side state between calls
- **User Isolation**: All tools require user_id and enforce ownership at query level
- **Tool Chaining**: Tools designed to be safely called by other tools
- **Async Performance**: Full async/await support for concurrent operations
- **Error Handling**: Structured errors (400, 401, 403, 404, 500) with descriptive messages

## MCP Server Architecture

### Server Structure

```
backend/
├── mcp_server.py      # Main MCP server with FastAPI integration
├── mcp_tools.py       # Tool implementations
├── mcp_config.py      # Server configuration
└── main.py            # Updated with MCP server startup
```

### Tool Signatures

| Tool | Parameters | Returns |
|------|------------|---------|
| `add_task` | user_id: str, title: str, description?: str, priority?: int, due_date?: str | {success: bool, task_id: str, task: dict} |
| `list_tasks` | user_id: str, status?: str, priority?: int | {success: bool, tasks: list[dict]} |
| `complete_task` | user_id: str, task_id: str | {success: bool, task: dict} |
| `delete_task` | user_id: str, task_id: str | {success: bool, deleted_task_id: str} |
| `update_task` | user_id: str, task_id: str, title?: str, description?: str, priority?: int, due_date?: str | {success: bool, task: dict} |

## Implementation Pattern

### MCP Server Setup

```python
from mcp.server.fastapi import FastAPIMCP
from fastapi import FastAPI

app = FastAPI()
mcp_server = FastAPIMCP(app)

@mcp_server.tool()
async def add_task(user_id: str, title: str, description: str = None) -> dict:
    """Add a new task for the specified user."""
    # Extract user_id from context
    # Validate parameters
    # Execute with user_id filter: WHERE user_id = :user_id
    # Return structured JSON response
```

### Database Session Management

```python
from sqlalchemy.ext.asyncio import create_async_engine, AsyncSession
from sqlalchemy.orm import sessionmaker

engine = create_async_engine(DATABASE_URL)
async_session = sessionmaker(engine, class_=AsyncSession, expire_on_commit=False)

async def get_db_session():
    async with async_session() as session:
        yield session
```

### User ID Enforcement

```python
async def add_task(user_id: str, title: str, ...) -> dict:
    if not user_id:
        raise ValueError("user_id is required")

    # Always filter by user_id in queries
    statement = select(Task).where(
        Task.id == task_id,
        Task.user_id == user_id  # Critical for isolation
    )
```

## Tool Implementation Checklist

For each tool, implement:

1. **Parameter Validation**: Check required fields, types, and constraints
2. **User ID Extraction**: Get user_id from request context or parameters
3. **Database Operation**: Execute with proper user_id filtering
4. **Response Construction**: Return structured JSON with success status
5. **Error Handling**: Catch exceptions and return appropriate error codes
6. **Logging**: Log operation outcomes for debugging

## Error Taxonomy

| Status | Condition | Example |
|--------|-----------|---------|
| 400 | Invalid input parameters | Missing required fields, invalid types |
| 401 | Missing/unauthorized user | No user_id provided |
| 403 | User not authorized | user_id doesn't match resource owner |
| 404 | Resource not found | Task doesn't exist |
| 500 | Internal error | Database connection failed |

## Tool Chaining Support

Design tools to support chaining:

```python
async def complete_task(user_id: str, task_id: str) -> dict:
    """Mark a task as complete. Can be called by other tools."""
    task = await get_task_by_id(user_id, task_id)
    if task:
        task.completed = True
        await session.commit()
    return {"success": True, "task": task_to_dict(task)}

async def list_tasks(user_id: str, status: str = None) -> dict:
    """List tasks. Supports filtering by status."""
    # This can chain to complete_task or other tools
```

## Dependencies

```txt
mcp>=0.9.0
fastapi>=0.100.0
sqlmodel>=0.0.14
sqlalchemy>=2.0.0
```

## Running the Server

```bash
cd backend
uvicorn mcp_server:app --host 0.0.0.0 --port 8001
```

## Integration with Main App

```python
# main.py
from mcp_server import mcp

app = FastAPI()
app.include_router(mcp.router)

@app.on_event("startup")
async def startup():
    await mcp.run()
```

## Verification Checklist

- [ ] All 5 tools registered and accessible
- [ ] User ID enforced in every database query
- [ ] JSON responses match specification
- [ ] Error handling returns appropriate codes
- [ ] Tool chaining works correctly
- [ ] Server starts without errors
- [ ] Database connections work

مجوز

مجوز اعلام‌شده: MIT

MIT License

Copyright (c) 2026 majiayu000

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.

مشاهدهٔ مجوز در مخزن منبع — نسخهٔ منتشرشده در آن‌جا مرجع است.