Lalaleap MCP Server

Через MCP (Model Context Protocol) AI-инструменты могут напрямую взаимодействовать с системой управления проектами Lalaleap.

После подключения вы сможете с помощью естественного языка попросить AI создать требования, найти ошибки, управлять задачами — не нужно переключаться в браузер.

Что это такое?

你（在 Claude Code / Cursor 裡打字）
  ↓  "幫我在彰基專案建一筆需求：病歷查詢 API"
Claude / Cursor（透過 MCP Protocol 呼叫 tool）
  ↓  callTool("create_requirement", { pno, title, priority })
Lalaleap MCP Server（本專案，TypeScript + stdio）
  ↓  POST /require/add → POST /require/edit
Lalaleap 後端 API（Java）
  ↓
回傳結果 → AI 告訴你「需求已建立，編號 1000160」

Одной фразой: это переводной слой между AI и Lalaleap.

Related MCP server: litejira-mcp

Быстрый старт (3 минуты)

Шаг 1: Настройте свой AI-инструмент

Не нужно вручную клонировать репозиторий — просто укажите GitHub repo в настройках MCP, npx автоматически загрузит и соберёт.

Claude Code — отредактируйте ~/.claude/settings.json:

{
  "mcpServers": {
    "lalaleap": {
      "command": "npx",
      "args": ["-y", "github:kuraki5336/tpi_lalaleap_mcp"],
      "env": {
        "LALALEAP_API_URL": "https://your-domain.com/ap2/lalaleap",
        "LALALEAP_EMAIL": "你的email@gmail.com",
        "LALALEAP_PASSWORD": "你的密碼",
        "LALALEAP_UNSAFE_SSL": "1"
      }
    }
  }
}

Cursor — в Settings → MCP добавьте сервер с теми же полями.

Предварительное условие: у пользователя должен быть доступ к GitHub repo (для private repo требуется SSH key или personal access token).

LALALEAP_UNSAFE_SSL=1 нужен, потому что в dev-среде истёк SSL-сертификат; в production не требуется.

Альтернатива: локальная установка

Если не хотите каждый раз загружать через npx, можно клонировать:

git clone https://github.com/kuraki5336/tpi_lalaleap_mcp.git
cd tpi_lalaleap_mcp && npm install

Затем в настройках MCP укажите локальный путь:

{
  "mcpServers": {
    "lalaleap": {
      "command": "node",
      "args": ["/你的路徑/tpi_lalaleap_mcp/dist/index.js"],
      "env": { ... }
    }
  }
}

Шаг 2: Начинайте использовать

Перезапустите ваш AI-инструмент и просто общайтесь.

Способы аутентификации

Поддерживаются два, на выбор:

Все переменные окружения:

Список доступных Tools

Всего 15 инструментов, AI автоматически выбирает, какой вызвать на основе вашей команды.

Проекты

Требования

Ошибки

Задачи / Спринты / Прочее

MCP Resources

Помимо tools (их нужно вызывать активно), есть resources (AI может читать их как контекст):

Примеры диалогов

你：幫我看一下有哪些專案
AI：→ list_projects
    你有 12 個專案：彰基_測試、ProjectC、...

你：在彰基_測試建一筆需求「病歷查詢 API」，優先度高
AI：→ list_projects（找到 pno）
    → create_requirement(pno, title="病歷查詢 API", priority="高")
    需求已建立，編號 1000160

你：列出這個專案所有需求
AI：→ list_requirements(pno)
    共 5 筆需求：
    1. 病歷查詢 API（高）- 規劃中
    2. 使用者登入（中）- 進行中
    ...

你：建一個 bug「登入頁按鈕在 Safari 沒反應」
AI：→ create_bug(pno, title="登入頁按鈕在 Safari 沒反應")
    缺陷已建立，編號 2000005

你：幫我加一個待辦「寫 API 文件」，截止下週五
AI：→ create_todo(pno, title="寫 API 文件", due_date="2026-03-28")
    待辦已建立

Архитектура и обзор исходного кода

tpi_tpad_mcp/
├── src/
│   ├── index.ts            # 入口：啟動 MCP Server、註冊 tools & resources
│   ├── config.ts           # 讀取環境變數
│   ├── api-client.ts       # axios HTTP client，處理登入/token/重試
│   ├── resources.ts        # 5 個 MCP Resources 定義
│   ├── test.ts             # API 整合測試（14 個端點）
│   ├── test-mcp.ts         # MCP Protocol E2E 測試（50 個案例）
│   └── tools/
│       ├── projects.ts     # list_projects, get_project_detail, create_project
│       ├── requirements.ts # create/list/get/update requirement
│       ├── bugs.ts         # create_bug, list_bugs
│       ├── todos.ts        # create_todo, list_todos
│       ├── sprints.ts      # list_sprints
│       ├── tags.ts         # search_tags
│       └── members.ts      # list_project_members
├── docs/
│   └── test-report.md      # QA 測試報告
├── package.json
└── tsconfig.json

Ключевые решения в дизайне

• Автоматическая аутентификация: автоматический вход при запуске, автоматическое обновление токена при 401, повторный вход при неудаче

• Двухшаговое создание: при создании требования/ошибки сначала POST /add для получения номера, затем POST /edit для заполнения полей (как в клиентской части)

• Никакие ошибки не приводят к падению: каждый tool обёрнут в try-catch, возвращается дружественное сообщение на китайском

• Защита записи: механизм WriteGuard защищает все операции записи (подробнее ниже)

Защита безопасности (WriteGuard)

AI может неправильно понять команду и массово записать мусорные данные. Все операции записи (create/update) защищены тремя уровнями:

1. Режим только для чтения

Полностью запрещает запись, AI может только запрашивать, но не создавать/изменять:

{
  "env": {
    "LALALEAP_READONLY": "1"  // 所有 create/update tool 會被直接阻擋
  }
}

Сценарии использования: Демо, когда новичок не уверен в поведении AI, или только для запросов.

2. Белый список проектов

Ограничивает запись AI только определёнными проектами, предотвращая работу с неправильными проектами:

{
  "env": {
    // 只允許對這兩個專案做寫入操作，其他專案的 create/update 會被阻擋
    "LALALEAP_ALLOWED_PROJECTS": "be3fd182-3696-41a6-bce8-7f2e9d88b648,c53f210f-xxxx"
  }
}

Сценарии использования: В production открыт только тестовый проект, члены команды работают только со своими проектами.

3. Ограничение частоты записи

Ограничивает максимальное количество записей в минуту, предотвращая массовое создание элементов за короткое время:

{
  "env": {
    "LALALEAP_WRITE_RATE_LIMIT": "5"  // 每分鐘最多 5 次寫入（預設 10）
  }
}

При превышении лимита AI получает чёткое сообщение об ошибке:

[頻率限制] 過去一分鐘已執行 5 次寫入操作（上限 5 次）。請稍後再試。

Сценарии использования: Предотвращение массового создания в цикле, неправильного понимания команд типа "создай 100 требований".

Рекомендуемые комбинации настроек

Разработка

# 開發模式（tsx 直接跑，不需編譯）
npm run dev

# 編譯
npm run build

# API 整合測試（直接打 API，14 個端點）
npm test

# MCP Protocol E2E 測試（透過 stdio 模擬真實 MCP 連線，50 個案例）
LALALEAP_UNSAFE_SSL=1 npx tsx src/test-mcp.ts

Добавление нового Tool

1. Добавьте или измените соответствующий файл в src/tools/

2. Зарегистрируйте с помощью server.tool(name, description, zodSchema, handler)

3. Если это новый файл, импортируйте и вызовите функцию регистрации в src/index.ts

4. Запустите тесты для проверки

// 範例：新增一個 tool
server.tool(
  'my_new_tool',
  '這個 tool 做什麼',
  {
    pno: z.string().describe('專案編號'),
    someParam: z.string().optional().describe('說明'),
  },
  async ({ pno, someParam }) => {
    try {
      const resp = await api.post('/some/endpoint', { pno, someParam });
      return {
        content: [{ type: 'text', text: JSON.stringify(resp.data, null, 2) }],
      };
    } catch (err) {
      return {
        content: [{ type: 'text', text: formatError(err) }],
        isError: true,
      };
    }
  }
);

Troubleshooting

Технологический стек

Покрытие тестами

Полный отчёт о тестах см. в docs/test-report.md.