MCP Server с нуля
Полное руководство для разработчиков

Почему AI нужен MCP Server: LLM без инструментов — лишь «говорящий мозг»

Training cutoff у LLM фиксирован; CRM, Git-репозитории и internal API недоступны из weights. До 2024 для Claude писали Function Calling, для GPT — Plugins, для Cursor — отдельный формат: смена модели = переписывание adapter layer с нуля. MCP Server инкапсулирует tool capability в изолированный процесс — один раз написали, используете в Claude Desktop / Cursor / Gemini.

Типовые сценарии: SQL-запрос к Postgres из Claude Desktop; Cursor Agent читает project docs и правит код; GPT дергает ticketing system через HTTP MCP — под капотом один и тот же Server process.

Что даёт гайд: не теорию ради теории, а путь от say_hello до production-grade knowledge-base Server с vector retrieval. Целевая аудитория: разработчики с базой Python или TypeScript, расширяющие AI в IDE или Desktop host.

Шесть pain points: почему «обёртка над REST API» не решает задачу

1. 01

   Vendor lock-in: OpenAI Function Calling и Claude Tool Use — разные JSON Schema и lifecycle; каждая смена вендора требует нового adapter.

2. 02

   Tools не discoverable: REST живёт в static docs; runtime tools/list для автономного discovery capability отсутствует.

3. 03

   IDE silos: Cursor, VS Code extensions и JetBrains plugins описывают tools по-разному — N×M интеграций вместо одного Server.

4. 04

   Context/data split: LLM не может стабильно читать config, user prefs или live logs — нужен standardized read-only channel через Resources.

5. 05

   Prompt templates разбросаны: code review, incident postmortem — нет единого registry; команды копируют шаблоны вручную.

6. 06

   Local vs remote deploy chaos: stdio subprocess подходит для dev, но production HTTP gateway, auth и monitoring без общего паттерна (см. гайд по stdio subprocess governance).

Dev environment: Python FastMCP vs TypeScript SDK

Два основных стека: Python mcp + FastMCP (data/script, быстрый prototype) и TypeScript @modelcontextprotocol/sdk (Web/API integration, compile-time type safety). SDK repos: python-sdk, typescript-sdk.

# Python stack
python -m venv .venv && source .venv/bin/activate
pip install "mcp[cli]" httpx pydantic

# TypeScript stack
npm init -y && npm install @modelcontextprotocol/sdk zod
npm install -D typescript tsx @types/node

Рекомендуемая структура проекта

my-mcp-server/
├── pyproject.toml          # или package.json
├── src/
│   ├── server.py           # FastMCP entrypoint
│   ├── tools/              # tool modules
│   ├── resources/          # Resource providers
│   └── prompts/            # Prompt templates
├── tests/
│   └── test_tools.py       # pytest + ClientSession
├── Dockerfile
└── README.md

Шестишаговый checklist готовности окружения

1. 01

   Выбор стека: data/ML — Python; Node fullstack — TypeScript.

2. 02

   Virtual env + lock dependencies: pip freeze или package-lock.json — иначе schema drift между dev и prod.

3. 03

   MCP Inspector: npx @modelcontextprotocol/inspector — visual debug JSON-RPC frames.

4. 04

   Claude Desktop config: правка ~/Library/Application Support/Claude/claude_desktop_config.json, добавление command/args Server.

5. 05

   Cursor config: Settings → MCP → Add Server; для stdio — python -m src.server или absolute path к interpreter.

6. 06

   Verify Inspector: запуск Server → connect Inspector → tools/list возвращает non-empty list.

// Cursor / Claude Desktop MCP config
{
  "mcpServers": {
    "my-tools": {
      "command": "python",
      "args": ["-m", "src.server"],
      "env": { "API_KEY": "your-key" }
    }
  }
}

Tools deep dive: от Schema к пяти production-grade tools

Tools — core capability MCP: AI выполняет side-effect operations через tools/call. Каждый Tool экспонирует name, description, inputSchema; FastMCP валидирует через Pydantic models.

from pydantic import BaseModel, Field

class SearchInput(BaseModel):
    query: str = Field(..., description="Поисковый запрос")
    limit: int = Field(10, ge=1, le=100, description="Число результатов")

@mcp.tool()
async def search_docs(params: SearchInput) -> str:
    """Поиск по документам"""
    results = await index.search(params.query, params.limit)
    return json.dumps(results, ensure_ascii=False)

Пять типовых Tool patterns

• calculator: safe eval или ast.literal_eval; exec запрещён.
• file_read / file_write: root directory whitelist против path traversal.
• fetch_url (async): httpx + timeout + domain whitelist.
• db_query: read-only SQL, parameterized queries; DDL запрещён.
• get_current_time: ISO8601 с timezone — против time hallucination LLM.

import httpx
from datetime import datetime, timezone

@mcp.tool()
async def fetch_url(url: str) -> str:
    """HTTP GET (domain whitelist)"""
    allowed = ("api.github.com", "nodemini.com")
    if not any(url.startswith(f"https://{d}") for d in allowed):
        raise ValueError(f"Domain not allowed: {url}")
    async with httpx.AsyncClient(timeout=10.0) as client:
        resp = await client.get(url)
        resp.raise_for_status()
        return resp.text[:8000]

@mcp.tool()
def get_current_time() -> str:
    """Текущее UTC время"""
    return datetime.now(timezone.utc).isoformat()

Error handling: operational checklist

• Structured errors: raise ValueError("human-readable msg") — Client передаёт message обратно в LLM context.
• Retryable vs fatal: network timeout помечайте retryable; permission denied — fail fast.
• Logging + redaction: log tool name и latency; не логируйте API keys и PII целиком.
• Idempotency: write operations с idempotency_key — защита от duplicate Agent calls.

Prompts: переиспользуемые multi-turn templates

MCP Prompt — conversation skeleton, зарегистрированный на Server. Client получает message list через prompts/get с ролями user / assistant и parameter placeholders — team-wide code review и incident workflow без per-user prompt files.

from mcp.types import PromptMessage, TextContent

@mcp.prompt()
def code_review_prompt(language: str = "python") -> list[PromptMessage]:
    """Стандартный Code Review template"""
    return [
        PromptMessage(role="user", content=TextContent(
            type="text",
            text=f"Ты senior {language} engineer. Проверь diff по security, performance, readability."
        )),
        PromptMessage(role="assistant", content=TextContent(
            type="text",
            text="Вставь diff или укажи PR — выдам structured review по CHECKLIST."
        )),
    ]

Variables ({ticket_id}, {severity}) versionируются на Server; upgrade Server у Client = вся команда на актуальном review standard.

Debug и тесты: Inspector + pytest unit tests

MCP Inspector — official visual debugger: connect через stdio или URL, manual tools/list / tools/call, inspect JSON-RPC round trips — на порядок быстрее, чем reverse-engineering Cursor logs.

# tests/test_tools.py
import pytest
from mcp import ClientSession, StdioServerParameters
from mcp.client.stdio import stdio_client

@pytest.mark.asyncio
async def test_say_hello():
    params = StdioServerParameters(command="python", args=["-m", "src.server"])
    async with stdio_client(params) as (read, write):
        async with ClientSession(read, write) as session:
            await session.initialize()
            result = await session.call_tool("say_hello", {"name": "MCP"})
            assert "MCP" in result.content[0].text

Таблица типовых ошибок

Hands-on: ChromaDB knowledge base MCP Server

Vectorize internal Wiki / Markdown и expose index_document, search_knowledge, write_note — Cursor Agent сначала ищет в company knowledge base, затем пишет код с grounded context.

Requirements: incremental indexing (watchfiles на docs/), semantic search Top-K, optional scratchpad writes.

import chromadb
from chromadb.utils.embedding_functions import SentenceTransformerEmbeddingFunction

client = chromadb.PersistentClient(path="./data/chroma")
collection = client.get_or_create_collection(
    "wiki", embedding_function=SentenceTransformerEmbeddingFunction()
)

@mcp.tool()
def search_knowledge(query: str, top_k: int = 5) -> str:
    """Semantic search по internal KB"""
    hits = collection.query(query_texts=[query], n_results=top_k)
    return json.dumps(hits["documents"][0], ensure_ascii=False)

@mcp.tool()
def index_document(path: str) -> str:
    """Index одного Markdown файла"""
    text = open(path).read()
    collection.upsert(ids=[path], documents=[text], metadatas=[{"path": path}])
    return f"Indexed: {path}"

Cursor demo query: «найди в knowledge base документы про MCP HTTP deploy и сформулируй three-step launch checklist» — Agent вызывает search_knowledge, затем отвечает по retrieved context. На большем scale vector store заменяют на Qdrant (remote gRPC).