Документация MCP Project+apps

MCP нужен прежде всего для чтения контекста Project+apps и навигации по продуктовому штабу без raw data. Основной write-контракт для внешних агентов живёт в HTTP API.

Роль MCP в агентной работе

В Project+apps MCP считается прежде всего контуром чтения и навигации: агент читает контекст, канон и карту портфеля, а затем принимает решение, что нужно создать или обновить.

• MCP подходит для чтения summary-контекста, канона и поиска существующих объектов.
• Write-tools в MCP требуют входные arguments.
• Если конкретный MCP-клиент не умеет передавать payload в tool call, запись через MCP write-tools использовать нельзя.
• В таком случае агент должен оставить MCP для чтения, а запись выполнять через HTTP API Project+apps с заголовком X-Project-Apps-Token.

Основное подключение

Для локальной работы основной MCP endpoint должен смотреть в локальный Project+apps, а не в публичный домен.

{
  "mcpServers": {
    "project-apps": {
      "url": "http://127.0.0.1:8010/mcp/project-apps"
    }
  }
}

Cursor config

{
  "mcpServers": {
    "project-apps": {
      "url": "http://127.0.0.1:8010/mcp/project-apps"
    },
    "project-apps-stdio": {
      "command": "php",
      "args": [
        "C:\Users\MSI\Desktop\ProjectWatch\artisan",
        "mcp:start",
        "project-apps"
      ]
    }
  }
}

• project-apps — основной локальный web MCP.
• project-apps-stdio — запасной локальный stdio-вариант.

Stdio fallback

Если web MCP не используется, сервер можно поднять как stdio-handle.

php artisan mcp:start project-apps

Промпты

• project_apps_director_brief — краткий директорский бриф по сводке портфеля и блоку внимания (опциональные аргументы: direction_slug, product_slug, status).

Пример вызова промпта (prompts/get)

{
  "jsonrpc": "2.0",
  "id": 40,
  "method": "prompts/get",
  "params": {
    "name": "project_apps_director_brief",
    "arguments": {
      "direction_slug": "fitness",
      "product_slug": "push-ups"
    }
  }
}

Точное имя промпта и доступные аргументы уточняйте через prompts/list на вашей версии сервера.

Инструменты

• project_apps_overview — директорская сводка портфеля: здоровье, продукты, риски, рост и блок внимания.
• project_apps_attention — всё, что требует внимания сейчас: проблемы, риски, источники и рекомендуемые действия.
• project_apps_canon — прочитать постоянные правила Project+apps: что считать продуктом, freeze и каноническую структуру.
• project_apps_product_search — поиск продуктов по направлению, slug, статусу и текстовому запросу.
• project_apps_create_*, project_apps_update_* и соседние write-tools — слой совместимости для клиентов, которые действительно умеют передавать arguments (или эквиваленты ниже).
• project_apps_create_product — создать продукт с портфельным статусом, фокусом, монетизацией, здоровьем и следующим шагом.
• project_apps_update_product — обновить продукт: статус, фокус, здоровье, денежность и следующий шаг.
• project_apps_create_app — создать приложение как реализацию продукта.
• project_apps_update_app — обновить приложение: platform, store links и статус реализации.
• project_apps_record_decision — записать жёсткое решение по продукту, направлению или приложению, а при необходимости сразу породить задачи.
• project_apps_create_task — создать рабочую задачу с привязкой к продукту, направлению, приложению или решению.
• project_apps_create_canon_rule — создать каноническое правило внутри apps.
• project_apps_update_canon_rule — обновить каноническое правило.

Протокол JSON-RPC, методы и формат тела запроса

Web MCP принимает одно JSON-RPC 2.0 сообщение в теле POST (обычно Content-Type: application/json). Ответ — JSON; при стриминге возможен SSE (зависит от транспорта клиента).

• initialize — первое сообщение сессии (протокол MCP); дальше клиент работает с тем же endpoint.
• tools/list — список имён и схем входных данных инструментов.
• tools/call — вызов инструмента: обязателен params.name и полезная нагрузка для аргументов (см. ниже).
• resources/read — чтение ресурса по URI (project-apps://context и др.).

Минимальное тело для tools/call

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "project_apps_overview",
    "arguments": {}
  }
}

Где могут лежать аргументы инструмента (приоритет сверху вниз)

1. params.arguments — объект JSON (основной вариант).
2. params.input, params.payload, params.body — те же данные под другим именем (совместимость).
3. params._meta.arguments / params._meta.input — редкие клиенты.
4. Строка JSON вместо объекта для полей выше — будет распарсена.
5. Плоский fallback: после удаления служебных ключей (name, arguments, input, …) оставшиеся поля верхнего уровня params считаются аргументами инструмента (legacy-клиенты).

Пример: список инструментов (tools/list)

curl -sS -X POST "https://apps.farmchel.org/mcp/project-apps" \
  -H "Content-Type: application/json" \
  -d "{\"jsonrpc\":\"2.0\",\"id\":1,\"method\":\"tools/list\",\"params\":{}}"

Пример: обзор портфеля (tools/call)

curl -sS -X POST "https://apps.farmchel.org/mcp/project-apps" \
  -H "Content-Type: application/json" \
  -d "{\"jsonrpc\":\"2.0\",\"id\":2,\"method\":\"tools/call\",\"params\":{\"name\":\"project_apps_overview\",\"arguments\":{}}}"

Пример: чтение ресурса контекста (resources/read)

curl -sS -X POST "https://apps.farmchel.org/mcp/project-apps" \
  -H "Content-Type: application/json" \
  -d "{\"jsonrpc\":\"2.0\",\"id\":3,\"method\":\"resources/read\",\"params\":{\"uri\":\"project-apps://context\"}}"

Справочник инструментов (кратко)

Ниже — ориентир для агентов; точная JSON Schema приходит из tools/list у живого сервера.

Обновление продукта: snake_case, camelCase и проверка результата

Один и тот же апдейт можно отправить в «админском» стиле полей или как в TypeScript. После нормализации ключей сервер валидирует и сохраняет данные. В ответе смотрите applied_field_keys: там перечислены поля, которые реально попали в обновление (без идентификаторов product_id / product_slug).

Вариант A — snake_case

{
  "jsonrpc": "2.0",
  "id": 10,
  "method": "tools/call",
  "params": {
    "name": "project_apps_update_product",
    "arguments": {
      "product_slug": "push-ups",
      "health_summary": "Актуальный паспорт здоровья после ревью.",
      "portfolio_status": "core",
      "next_step": "Согласовать рост канала."
    }
  }
}

Вариант B — camelCase (эквивалентно полям из варианта A)

{
  "jsonrpc": "2.0",
  "id": 11,
  "method": "tools/call",
  "params": {
    "name": "project_apps_update_product",
    "arguments": {
      "productSlug": "push-ups",
      "healthSummary": "Актуальный паспорт здоровья после ревью.",
      "portfolioStatus": "core",
      "nextStep": "Согласовать рост канала."
    }
  }
}

Фрагмент успешного ответа (упрощённо)

{
  "result": {
    "structuredContent": {
      "message": "Продукт обновлён в Project+apps.",
      "applied_field_keys": [
        "health_summary",
        "portfolio_status",
        "next_step"
      ],
      "id": 12,
      "slug": "push-ups",
      "portfolio_status": "core",
      "product_focus": "scale"
    }
  }
}

Примеры write-инструментов

Ниже в блоках <pre> для краткости показан только фрагмент params инструмента (поля name и arguments). Полный HTTP-запрос всегда оборачивается в JSON-RPC 2.0, как в разделе «Протокол JSON-RPC» и в примерах с curl выше.

Создать продукт

{
  "name": "project_apps_create_product",
  "arguments": {
    "direction_slug": "fitness",
    "name": "Бег",
    "portfolio_status": "next",
    "product_focus": "assess-development",
    "summary": "Кандидат в новый фитнес-продукт.",
    "next_step": "Проверить app map и economics."
  }
}

Обновить продукт

{
  "name": "project_apps_update_product",
  "arguments": {
    "product_slug": "push-ups",
    "portfolio_status": "core",
    "product_focus": "scale",
    "is_revenue_generating": true,
    "is_favorite": true,
    "health_summary": "Экономика подтверждена, продукт можно усиливать."
  }
}

Записать решение

{
  "name": "project_apps_record_decision",
  "arguments": {
    "product_slug": "push-ups",
    "title": "Масштабировать после подтверждения stores",
    "decision_type": "scale",
    "owner": "Growth",
    "decision": "Не масштабировать без store truth.",
    "review_at": "2026-04-30",
    "tasks": [
      {
        "title": "Проверить store truth по Отжиманиям",
        "owner": "Growth",
        "priority": "high"
      }
    ]
  }
}

Прочитать канон

{
  "name": "project_apps_canon",
  "arguments": {
    "status": "active",
    "limit": 10
  }
}

Создать приложение

{
  "name": "project_apps_create_app",
  "arguments": {
    "product_slug": "push-ups",
    "name": "Отжимания Android",
    "platform": "Android",
    "implementation_status": "building",
    "store_url": "https://play.google.com/store/apps/details?id=org.farmchel.pushups.android",
    "bundle_id": "org.farmchel.pushups.android",
    "package_id": "org.farmchel.pushups.android"
  }
}

Спорный app-хвост внутри направления

{
  "name": "project_apps_create_app",
  "arguments": {
    "direction_slug": "fitness",
    "name": "Quit Alcohol Android",
    "platform": "Android",
    "implementation_status": "building",
    "product_binding_status": "product-candidate",
    "product_candidate_name": "Quit Alcohol",
    "package_id": "org.farmchel.quit.alcohol"
  }
}

Создать задачу

{
  "name": "project_apps_create_task",
  "arguments": {
    "product_slug": "push-ups",
    "title": "Собрать store links по Отжиманиям",
    "owner": "Operations",
    "status": "open",
    "priority": "high",
    "due_at": "2026-04-20"
  }
}

Создать каноническое правило

{
  "name": "project_apps_create_canon_rule",
  "arguments": {
    "title": "Один продукт может иметь несколько приложений",
    "rule_type": "summary-contract",
    "body": "Продукт не равен одному приложению, если смысл общий и решения принимаются на уровне продукта."
  }
}

Альтернатива arguments: объект input

Часть клиентов кладёт данные в params.input — это поддерживается наравне с arguments. Для создания продукта так удобнее обходить коллизию имён (имя инструмента в params.name и человекочитаемое название продукта внутри input.name).

{
  "jsonrpc": "2.0",
  "id": 50,
  "method": "tools/call",
  "params": {
    "name": "project_apps_create_product",
    "input": {
      "direction_slug": "fitness",
      "name": "Ходьба",
      "portfolio_status": "next",
      "product_focus": "assess-development",
      "summary": "Создание через params.input."
    }
  }
}

Обновить приложение (project_apps_update_app)

{
  "jsonrpc": "2.0",
  "id": 51,
  "method": "tools/call",
  "params": {
    "name": "project_apps_update_app",
    "arguments": {
      "mobile_app_slug": "push-ups-ios",
      "store_url": "https://apps.apple.com/app/id000000000",
      "implementation_status": "implemented",
      "bundle_id": "org.farmchel.pushups.ios"
    }
  }
}

Идентификация приложения — только mobile_app_id или mobile_app_slug. В ответе — applied_field_keys без этих двух полей.

Обновить правило канона (project_apps_update_canon_rule)

{
  "jsonrpc": "2.0",
  "id": 52,
  "method": "tools/call",
  "params": {
    "name": "project_apps_update_canon_rule",
    "arguments": {
      "canon_rule_id": 3,
      "body": "Уточнённая формулировка правила после ревью.",
      "status": "active"
    }
  }
}

Ресурсы

• project-apps://context — канонический контекст системы, MCP и API endpoint-ы, правила и сущности.
• project-apps://canon — активный канон Project+apps.
• project-apps://portfolio — карта направлений, продуктов и приложений.

Таблица окружений и портов

Отладка: «ответ успешный, а в админке не изменилось»

• Проверьте tools/call → result.structuredContent.applied_field_keys для update-инструментов. Пустой массив означает, что до слоя сохранения не дошло ни одного изменяемого поля (часто неправильные имена или клиент не передал вложенный arguments).
• Убедитесь, что используются поля из JSON Schema инструмента (tools/list). Произвольные ключи отбрасываются валидацией.
• Пробуйте явный snake_case; если клиент шлёт только camelCase, сервер их нормализует — при проблемах смотрите ответ и логи валидации.
• Убедитесь, что запись через MCP не отключена: переменная окружения PROJECT_APPS_MCP_WRITE_ENABLED=false убирает write-tools из списка (tools/list не содержит create/update).
• Сравните окружение: локальный MCP на порту 8010 и прод на 443 — это разные базы данных.
• Надёжный альтернативный путь записи — HTTP API с заголовком X-Project-Apps-Token, если MCP-клиент не передаёт аргументы стабильно.

Что возвращает MCP context

{
  "mcp": {
    "local_handle": "project-apps",
    "stdio_command": "php artisan mcp:start project-apps",
    "local_web_endpoint": "http://127.0.0.1:8010/mcp/project-apps",
    "local_port": "8010/HTTP",
    "public_web_endpoint": "https://apps.farmchel.org/mcp/project-apps",
    "public_port": "443/HTTPS"
  }
}

Правило работы

• MCP работает только с summary-уровнем.
• Через MCP не запрашиваем raw events, raw installs, raw reviews, raw store dumps и ad-cabinet noise.
• Совместимые MCP write-tools существуют, но продовый и рекомендуемый write-path для внешних агентов — HTTP API с X-Project-Apps-Token.
• Если агент работает локально, он должен ходить в локальный endpoint на порту 8010.