mcp-tma-builder

MCP-сервер знаний по разработке Telegram Mini Apps и TON blockchain. AI-агент спрашивает — сервер отвечает, используя Qwen Code и базу из 55 документов (29,500+ строк).

Архитектура

AI-агент (docker-git у пользователя)
    |
    MCP tool: search({ query: "..." })
    |
    mcp-tma-client (npm-пакет, stdio-to-SSE bridge)
    | HTTP
    v
Express сервер (VPS)
    |-- Rate limit (10 req/s по IP)
    |-- /sse -> MCP SSE Transport
    |             |
    v             v
         Qwen Code (Docker-контейнер)
              |
              knowledge/ (55 markdown-файлов)

Требования

Node.js 20+
Docker + Docker Compose
GPU или достаточно RAM для Qwen Code

Установка

git clone https://github.com/SpawnDock/MCP.git
cd MCP
npm install
cp .env.example .env

Переменные окружения

PORT=3000
RATE_LIMIT_RPS=10
QWEN_MODE=http
QWEN_API_URL=http://localhost:8080
QWEN_TIMEOUT_MS=60000
QWEN_CODE_COMMAND=qwen
QWEN_CODE_AUTH_TYPE=qwen-oauth
PUBLIC_ORIGIN=http://localhost:3000

# Продакшен с docker-compose.prod.yml: см. .env.example — PUBLIC_HOST (:80 или FQDN), PUBLIC_ORIGIN без :3000 (наружу 80/443 через Caddy).

TELEGRAM_BOT_TOKEN=
TELEGRAM_BOT_USERNAME=rustgpt_bot
TELEGRAM_MINI_APP_SHORT_NAME=tma
CONTROL_PLANE_URL=http://localhost:3000
BOT_POLL_TIMEOUT=25

TELEGRAM_*, CONTROL_PLANE_URL и BOT_POLL_TIMEOUT нужны для npm run bot или npm run bot:dev. Бот использует TELEGRAM_BOT_USERNAME и TELEGRAM_MINI_APP_SHORT_NAME, чтобы отдавать TMA deep link вида https://t.me/rustgpt_bot/tma?startapp=<slug>.

Если те же TELEGRAM_BOT_TOKEN, TELEGRAM_BOT_USERNAME и TELEGRAM_MINI_APP_SHORT_NAME заданы процессу MCP/API (npm start / npm run dev), при первом подключении dev-tunnel к проекту владелец получит сообщение в Telegram со ссылками на превью.

Режимы Qwen / поиска по базе знаний:

QWEN_MODE=http (по умолчанию) — запрос к HTTP API (QWEN_API_URL или OpenRouter при OPENROUTER_KEY).
QWEN_MODE=cli — локальный бинарь qwen на машине, где запущен API (QWEN_CODE_COMMAND, QWEN_CODE_CWD, QWEN_CODE_AUTH_TYPE).
QWEN_MODE=container — каждый поиск вызывает docker/podman run с образом QWEN_CONTAINER_IMAGE; каталог knowledge/ монтируется только для чтения в QWEN_CONTAINER_CORPUS_PATH. Сборка образа, пример docker run и обновление корпуса без пересборки: docker/qwen-search/README.md. Переменные QWEN_CONTAINER_* и опционально QWEN_KNOWLEDGE_HOST_PATH — в .env.example.

Для cli: QWEN_CODE_AUTH_TYPE=qwen-oauth ожидает OAuth credentials в ~/.qwen/oauth_creds.json.

Запуск (разработка)

npm run build
npm start

Или:

npm run dev

Для локального polling-бота:

npm run bot:dev

Локальная разработка в Docker (`docker-compose.yml`)

Полный локальный стек с HTTPS (Caddy tls internal) для проверки сценариев, где нужен https:// на этой машине.

mkdir -p data/state
npm run build
npm run docker:dev
# или: docker compose up -d --build

Сервисы:

qwen — Qwen Code, порт 8080 на хосте (удобно для гибрида: только Qwen в Docker, npm run dev на хосте с QWEN_API_URL=http://127.0.0.1:8080).
mcp-server — API и MCP, http://localhost:3000 и через Caddy https://localhost (и https://127.0.0.1).
caddy — 80/443, лендинг на /, остальное — прокси на MCP.

Базовые переменные для compose лежат в deploy/spawndock-docker-dev.stack (PUBLIC_ORIGIN=https://localhost). Секреты и TELEGRAM_* задавайте в корневом .env (рядом с docker-compose.yml) — Compose подставит их в контейнеры.

Доверие локальному HTTPS (браузер): у Caddy внутренний CA. Экспорт корневого сертификата (один раз):

docker compose cp caddy:/data/caddy/pki/authorities/local/root.crt /tmp/spawndock-caddy-local.crt
# Далее импортируйте root.crt в доверенные корневые (Chrome: Настройки → Безопасность → Управление сертификатами) или см. документацию вашей ОС.

Telegram: long polling бот в том же compose: положите токен и username в .env, затем npm run docker:dev:telegram или docker compose --profile telegram up -d --build. Mini App из телефона по-прежнему нуждается в публичном HTTPS (туннель, например dev-tunnel / cloudflared / ngrok); https://localhost с ПК после импорта CA достаточно для проверки API и ссылок на этой машине.

Запуск (продакшен, Docker)

Продакшен на VPS: docker compose -f docker-compose.prod.yml — MCP, бот, образ поиска и Caddy на 80/443; порт 3000 наружу не публикуется. См. .env.example и OPERATOR.md.

Тесты

npm test

Tool: search

Единственный MCP tool. Принимает запрос на естественном языке, Qwen ищет по документации и формирует ответ.

Input:

{
  "query": "как реализовать корзину в TMA"
}

Output:

{
  "answer": "Для корзины используйте React-контекст...",
  "sources": [
    { "file": "templates/shop/components.md", "section": "Cart" },
    { "file": "guides/webapp-api.md", "section": "MainButton" }
  ]
}

Ограничения: query не пустой, максимум 2000 символов.

База знаний (knowledge/)

55 файлов, 29,500+ строк документации. Покрывает всю экосистему TMA + TON.

TMA разработка

guides/
  getting-started.md         -- создание проекта, Vite + React + TWA SDK
  webapp-api.md              -- WebApp API: MainButton, BackButton, HapticFeedback, Popup
  navigation.md              -- роутинг, BackButton, deep linking, табы
  theming.md                 -- темы Telegram, CSS-переменные, dark/light
  common-mistakes.md         -- 10 типичных ошибок с исправлениями
  advanced-tma-features.md   -- CloudStorage, BiometricManager, QR-сканер, Invoice, Fullscreen, Accelerometer
  performance.md             -- бандл, lazy loading, виртуализация, кэширование
  testing-tma.md             -- моки WebApp SDK, TON Connect, Playwright E2E
  security.md                -- initData HMAC, CSP, XSS, rate limiting
  workflows.md               -- 6 end-to-end воркфлоу (beginner -> advanced)

Деплой

guides/deploy/
  cloudflare-pages.md        -- Wrangler CLI, GitHub integration
  vercel.md                  -- Vercel CLI, конфигурация
  github-pages.md            -- GitHub Actions, SPA routing

TON Connect

guides/
  ton-connect.md             -- базовая интеграция: wallet, transfer, manifest
  ton-connect-advanced.md    -- get-методы, мульти-сообщения, TON Proof, Jetton/NFT
  ton-agentic-patterns.md    -- 3 модели AI-blockchain: Propose+Approve, Agentic, Read-Only

TON Blockchain

guides/
  ton-smart-contracts.md     -- Tolk, Tact, FunC, акторная модель, Blueprint
  ton-tvm.md                 -- TVM: стек, cells, газ, регистры, опкоды
  ton-jettons.md             -- TEP-74, мастер/кошелёк, минт/трансфер/сжигание
  ton-nft.md                 -- TEP-62, коллекции, метаданные, royalty, SBT
  ton-defi.md                -- AMM, стейкинг, DAO, multisig, DeDust/Ston.fi
  ton-swap-dex.md            -- DeDust, Ston.fi, Omniston, LP, swap UI
  ton-wallet-versions.md     -- v3r2, v4r2, v5r1, Agentic wallet сравнение
  ton-agentic-wallets.md     -- автономные AI-кошельки, operator/owner ключи
  ton-dns.md                 -- .ton, .t.me домены, TEP-81
  ton-sites.md               -- ADNL, RLDP, децентрализованный хостинг
  ton-storage.md             -- Bag of Cells, storage providers, файлы
  ton-payment-channels.md    -- off-chain каналы, микротранзакции
  ton-payments-tma.md        -- 5 способов оплаты: TON, Jetton, Stars, TON Pay, Invoice
  ton-analytics.md           -- forensics, мониторинг, whale alerts
  ton-transaction-tracking.md -- lifecycle, hash типы, polling, SSE
  ton-contract-security.md   -- 10 уязвимостей, аудит, TEP compliance
  ton-appkit.md              -- @ton/appkit, React hooks, swap integration

TMA шаблоны (6 типов)

templates/
  shop/       -- каталог, корзина, checkout (prompt.md + components.md)
  game/       -- Canvas/Phaser, лидерборд, скоринг
  landing/    -- hero, features, CTA
  quiz/       -- вопросы, таймер, результаты
  menu/       -- категории, корзина, доставка
  portfolio/  -- проекты, галерея, контакты

Справочники

reference/
  twa-sdk.md              -- @twa-dev/sdk API (все методы и типы)
  telegram-bot-api.md     -- Bot API для TMA
  ton-sdk.md              -- @ton/ton, @ton/crypto, tonweb
  ton-apis.md             -- TON Center, TON API (tonapi.io)
  ton-standards.md        -- TEP-62, TEP-64, TEP-74, TEP-66, TEP-81, TEP-85, TEP-89
  ton-popular-tokens.md   -- USDT, NOT, DOGS, STON, GRAM + адреса контрактов
  blueprint.md            -- Blueprint framework, Sandbox, деплой
  ton-explorers.md        -- Tonviewer, TON Scan, TONAPI, инструменты
  tolk-language.md        -- Tolk: синтаксис, типы, миграция с FunC
  ton-mcp-ecosystem.md    -- обзор всех MCP-серверов в экосистеме TON

MCP-клиент (для пользователей)

npm-пакет mcp-tma-client в packages/mcp-tma-client/. Работает как stdio-to-SSE bridge — AI-агент видит его как локальный MCP-сервер, а он проксирует запросы на бэкенд.

Конфигурация в проекте пользователя (.mcp.json):

{
  "mcpServers": {
    "tma-knowledge": {
      "command": "npx",
      "args": ["mcp-tma-client"],
      "env": {
        "MCP_SERVER_URL": "https://tma-api.example.com/sse"
      }
    }
  }
}

Спецификации (PRD)

docs/PRD-public-knowledge-search-service.md — публичный /knowledge API
docs/PRD-usage-dashboard-minimal.md — панель использования (SQLite); UI: /ops/usage (Basic Auth OPS_USAGE_*), пиксель лендинга: /ops/pixel/landing.gif

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

src/
  index.ts          -- точка входа, запуск Express
  server.ts         -- Express: CORS, rate limit, health, SSE
  mcp.ts            -- MCP server, tool search
  config.ts         -- env-переменные
  qwen/
    client.ts       -- HTTP-клиент к Qwen API
    parser.ts       -- парсинг ответа, fallback
    prompts.ts      -- системный промпт
packages/
  mcp-tma-client/   -- npm-пакет тонкого клиента
knowledge/          -- база знаний (55 файлов)
Dockerfile
docker-compose.yml

Name		Name	Last commit message	Last commit date
Latest commit History 189 Commits
.github		.github
bot-resource		bot-resource
data/usage		data/usage
deploy		deploy
docker		docker
docs		docs
infra		infra
knowledge		knowledge
openapi		openapi
scripts		scripts
src		src
.dockerignore		.dockerignore
.env.example		.env.example
.gitignore		.gitignore
DEPLOY.md		DEPLOY.md
Dockerfile		Dockerfile
OPERATOR.md		OPERATOR.md
README.md		README.md
docker-compose.prod.yml		docker-compose.prod.yml
docker-compose.yml		docker-compose.yml
package-lock.json		package-lock.json
package.json		package.json
tsconfig.json		tsconfig.json
vitest.config.ts		vitest.config.ts

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Repository files navigation

mcp-tma-builder

Архитектура

Требования

Установка

Переменные окружения

Запуск (разработка)

Локальная разработка в Docker (`docker-compose.yml`)

Запуск (продакшен, Docker)

Тесты

Tool: search

База знаний (knowledge/)

TMA разработка

Деплой

TON Connect

TON Blockchain

TMA шаблоны (6 типов)

Справочники

MCP-клиент (для пользователей)

Спецификации (PRD)

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

About

Uh oh!

Contributors

Uh oh!

Languages

Folders and files

Latest commit

History

Repository files navigation

mcp-tma-builder

Архитектура

Требования

Установка

Переменные окружения

Запуск (разработка)

Локальная разработка в Docker (docker-compose.yml)

Запуск (продакшен, Docker)

Тесты

Tool: search

База знаний (knowledge/)

TMA разработка

Деплой

TON Connect

TON Blockchain

TMA шаблоны (6 типов)

Справочники

MCP-клиент (для пользователей)

Спецификации (PRD)

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

About

Resources

Uh oh!

Stars

Watchers

Forks

Contributors

Uh oh!

Languages

Локальная разработка в Docker (`docker-compose.yml`)