Portfolio MCP Server

Сервер MCP (Model Context Protocol), который предоставляет портфолио Чэн-Юня Ву — проекты, навыки и резюме — в виде инструментов, которые может напрямую вызывать любой ИИ-ассистент, совместимый с MCP (Claude Desktop, Claude.ai Connectors, MCP Inspector и т.д.), вместо того чтобы парсить веб-сайт.

Зачем это существует

Я хотел по-настоящему понять, как работает MCP от начала до конца, а не просто читать об этом — поэтому я создал небольшой сервер, который превращает содержимое моего сайта-портфолио в структурированные инструменты. Это также намеренный повод освоить две вещи, с которыми я раньше мало работал: Docker и базовый CI/CD пайплайн, оба из которых постоянно упоминаются в вакансиях, на которые я ориентируюсь.

Related MCP server: personal-mcp

Что такое MCP, кратко

MCP — это открытый протокол (от Anthropic), который позволяет ИИ-ассистенту вызывать внешние «инструменты» — типизированные функции с именем, описанием и схемой — для получения актуальной информации или выполнения действий, вместо того чтобы полагаться только на свои обучающие данные или вставленный документ. Сервер объявляет свои инструменты; любой MCP-совместимый клиент может их обнаружить и вызвать. Этот проект — один из таких серверов: он объявляет четыре инструмента, основанных на данных моего портфолио.

Инструменты

Документация каждого инструмента — это то, что ИИ-ассистент на самом деле читает, чтобы решить, когда его вызывать — см. src/portfolio_mcp/server.py.

Охват: data/projects.json содержит все 31 элемент портфолио — 7 глубоких кейсов (запущенные системы, дипломная работа, исследовательский проект NSTC, наградная статья) плюс 24 более легких записи (другие конкурсные работы, курсовые отчеты, конференционные статьи). Каждый содержит хотя бы одну ссылку. Курсовые отчеты и сопутствующие статьи содержат идентификатор related_project, указывающий на более полный кейс, к которому они относятся, чтобы ассистент мог перейти от отчета к полной истории.

Архитектура

Claude Desktop / Claude.ai / MCP Inspector
              │  (stdio locally, or Streamable HTTP remotely)
              ▼
      MCPServer instance (server.py)
              │  registers 4 tools
              ▼
       tools.py  (pure, unit-tested logic)
              │
              ▼
   data_loader.py  →  data/*.json  (projects, skills, resume)

• Транспорт: Streamable HTTP, не stdio — смысл в том, что удаленный клиент (например, Claude.ai Connectors) может обращаться к этому серверу через публичный URL, а не только через локально запущенный процесс. Stdio по-прежнему поддерживается для локального тестирования с Claude Desktop / MCP Inspector.

• Уровень данных: три плоских JSON-файла в папке data/, загружаемые один раз и кэшируемые (functools.lru_cache). Никакой базы данных — данные небольшие, публичные и редко меняются.

• Логика инструментов vs. MCP-обвязка: намеренно разделены (tools.py vs. server.py), чтобы логику можно было тестировать модульно без запущенного MCP-сервера или транспорта.

• Примечание по SDK: официальный Python SDK mcp перенес свой высокоуровневый серверный API с FastMCP на mcp.server.mcpserver.MCPServer в версии 2.0.0 — этот проект нацелен на mcp>=2.0.0 и этот актуальный API. Если вы видели старые MCP-туториалы с from mcp.server.fastmcp import FastMCP, это API до версии 2.0, и он не импортируется с тем, что сейчас дает pip install mcp.

Структура проекта

portfolio-mcp-server/
├── data/                      # projects.json, skills.json, resume.json
├── src/portfolio_mcp/
│   ├── server.py              # MCPServer app: registers tools, stdio/HTTP entrypoints, /chat route
│   ├── tools.py                # MCP tool logic (testable, no MCP dependency)
│   ├── chat.py                  # /chat: Claude + Tool Runner over the same data, for the site's Q&A widget
│   └── data_loader.py          # cached JSON loading
├── tests/                      # pytest suite run in CI (tools, server security, chat, chat route)
├── Dockerfile                  # python:3.12-slim + uvicorn, Streamable HTTP
├── .github/workflows/ci.yml    # lint (ruff) + test (pytest) on every push
└── claude_desktop_config.json  # example config for local stdio testing

Локальный запуск

# from the repo root
python -m venv .venv && source .venv/bin/activate
pip install -e ".[dev]"

Вариант A — stdio, с MCP Inspector

npx @modelcontextprotocol/inspector python -m portfolio_mcp.server

Открывает локальный веб-интерфейс, где можно напрямую вызывать каждый инструмент и просматривать запрос/ответ.

Вариант B — stdio, с Claude Desktop

Объедините запись mcpServers из claude_desktop_config.json со своей собственной конфигурацией Claude Desktop (Settings → Developer → Edit Config), исправив пути для вашей машины, затем перезапустите Claude Desktop и задайте что-то вроде "Над какими проектами работал этот человек?"

Вариант C — Streamable HTTP, локально

TRANSPORT=http python -m portfolio_mcp.server
# equivalent — both serve the exact same ASGI app, /chat included:
uvicorn portfolio_mcp.server:app --host 0.0.0.0 --port 8000

Тесты

pytest -v
ruff check .

Запуск с Docker

docker build -t portfolio-mcp-server .
docker run -p 8000:8000 portfolio-mcp-server

Контейнер всегда обслуживает Streamable HTTP (в этом и смысл контейнеризации — переносимый, публично доступный модуль, а не процесс stdio, привязанный к одной машине).

Развертывание (Render)

Выбранная платформа для развертывания: Render, бесплатный тариф — он запускает долгоживущие контейнеры (не бессерверные функции с ограничениями по времени выполнения), что необходимо для постоянных соединений Streamable HTTP, и для начала работы не требуется кредитная карта.

1. Отправьте этот репозиторий на GitHub.

2. На render.com: New → Web Service → подключите этот репозиторий.

3. Render автоматически обнаружит Dockerfile и соберет/запустит его как контейнер.

4. Выберите тип инстанса Free → вы получите URL вида https://<что-то>.onrender.com.

5. Проверьте, что он работает:

   npx @modelcontextprotocol/inspector https://<something>.onrender.com/mcp

6. (Опционально) Включите автоматическое развертывание Render из GitHub, чтобы git push в main автоматически переразвертывал приложение — в сочетании с CI-пайплайном ниже это дает полную историю CI/CD.

Примечание по бесплатному тарифу: бесплатные веб-сервисы Render засыпают после ~15 минут бездействия и требуют 30-60 секунд на пробуждение при следующем запросе. Для демонстрации портфолио это нормально; стоит упомянуть как осознанный компромисс между стоимостью и задержкой, если спросят.

Рабочее развертывание: https://yun-portfolio-mcp.onrender.com/mcp — подключите MCP-клиент к этому URL (обратите внимание на путь /mcp; корневой домен возвращает 404, это ожидаемо — Streamable HTTP обслуживает только этот путь). Проверьте сами с помощью npx @modelcontextprotocol/inspector https://yun-portfolio-mcp.onrender.com/mcp.

Если вы форкнете этот проект: белый список заголовков Host в server.py по умолчанию жестко задан как yun-portfolio-mcp.onrender.com (защита от DNS-ребдинга отклоняет любой другой заголовок Host с кодом 421). Установите переменную окружения MCP_ALLOWED_HOSTS на имя хоста вашего развертывания или отредактируйте ALLOWED_HOSTS напрямую.

Чат-ендпоинт (/chat) — виджет Q&A для сайта портфолио

Вторая, отдельная точка входа на том же сервисе Render, предназначенная для простого чат-виджета, встроенного на yunwcy.github.io — не является частью описанного выше протокола MCP. Браузер отправляет POST с {"message": "..."} на /chat; сервер использует Anthropic Tool Runner, чтобы позволить Claude решить, какой из тех же четырех инструментов вызвать (путем прямого вызова tools.py — без MCP-рукопожатия), а затем возвращает {"reply": "..."}. Полная реализация — в src/portfolio_mcp/chat.py.

Почему для этого нужен настоящий бэкенд, а одного GitHub Pages недостаточно: ответ на естественном языке означает, что LLM должен увидеть вопрос и решить, какой инструмент вызвать, для чего нужен API-ключ Anthropic — а ключ никогда нельзя помещать в клиентский JavaScript на статическом сайте, так как любой может посмотреть исходный код и сжечь аккаунт. /chat хранит ключ на стороне сервера (переменная окружения Render, никогда не отправляется в браузер) и передает на GitHub Pages только тот виджет, который нужен браузеру.

Настройка (требуется, чтобы этот ендпоинт заработал):

1. Получите API-ключ в Anthropic Console и добавьте его в Render как переменную окружения ANTHROPIC_API_KEY (панель Render → этот сервис → Environment). Без него /chat возвращает 503 {"error": "not_configured"}, а не вызывает падение сервера.

2. CHAT_ALLOWED_ORIGINS (через запятую) управляет CORS — по умолчанию https://yunwcy.github.io. Установите его, если виджет когда-либо будет размещен в другом месте.

3. ANTHROPIC_CHAT_MODEL (по умолчанию claude-opus-5) — самый мощный универсальный выбор, но это простой, потенциально высоконагруженный и чувствительный к стоимости публичный виджет, поэтому claude-haiku-4-5 здесь стоит рассмотреть особо. Это осознанный выбор, оставленный на усмотрение того, кто запускает сервер, а не жестко заданный.

4. CHAT_RATE_LIMIT_PER_HOUR (по умолчанию 30) — простой лимит в памяти на IP, чтобы один посетитель не мог в одиночку накрутить счет. Сбрасывается при каждом перезапуске/переразвертывании и не распределяется между инстансами — достаточно для низкотрафикового личного сайта, но не является общей защитой от злоупотреблений.

CI/CD

.github/workflows/ci.yml запускается при каждом push/PR в main: устанавливает пакет, проверяет линтинг с помощью ruff и запускает набор тестов pytest. Автоматическое развертывание Render из GitHub (см. выше) отвечает за часть CD.

Заметки по безопасности / стоимости

• Поверхность инструментов MCP (/mcp) сама не вызывает никакую LLM — она только читает локальный JSON и возвращает его. Тот, кто подключается (их Claude, их токены), несет эти расходы, а не этот сервер.

• Ендпоинт /chat вызывает LLM, используя собственный API-ключ Anthropic этого сервера — в этом и заключается его смысл (браузер не может безопасно хранить ключ). Стоимость ограничена лимитом запросов на IP, effort: "low" и небольшим max_tokens; см. раздел о чат-ендпоинте выше для настройки параметров.

• Все данные уже являются публичными на моем сайте портфолио — на обоих ендпоинтах не реализована аутентификация, так как нет ничего приватного для защиты. Белый список CORS для /chat существует для контроля того, кто может тратить бюджет API, а не для защиты данных.

Обновление данных

Редактируйте JSON-файлы в папке data/ напрямую — id является стабильным идентификатором, с которым сравнивается get_project_details; все остальные поля свободные. Для обновления содержимого не требуется изменений кода.