Servidor MCP de Lalaleap

Permite que las herramientas de IA operen directamente el sistema de gestión de proyectos Lalaleap a través de MCP (Model Context Protocol).

Una vez conectado, puedes pedirle a la IA en lenguaje natural que cree requisitos, busque errores, gestione tareas pendientes, sin necesidad de abrir el navegador.

¿Qué es?

你（在 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」

En una frase: es la capa de traducción entre la IA y Lalaleap.

Related MCP server: litejira-mcp

Inicio rápido (3 minutos)

Paso 1: Configura tu herramienta de IA

No necesitas clonar manualmente, solo apunta al repositorio de GitHub en la configuración de MCP, npx lo descargará y construirá automáticamente.

Claude Code — Edita ~/.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 — En Settings → MCP, agrega un nuevo servidor con los mismos campos.

Requisito previo: La máquina del usuario debe tener acceso al repositorio de GitHub (para repos privados, se necesita configurar clave SSH o token de acceso personal).

LALALEAP_UNSAFE_SSL=1 es porque el certificado SSL del entorno de desarrollo ha caducado; en producción no es necesario.

Alternativa: Instalación local

Si no quieres que npx lo descargue cada vez, también puedes clonarlo:

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

Luego, en la configuración de MCP, apunta a la ruta local:

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

Paso 2: Empieza a usarlo

Reinicia tu herramienta de IA y ya puedes conversar directamente.

Métodos de autenticación

Se admiten dos, elige uno:

Todas las variables de entorno:

Resumen de herramientas disponibles

Hay 15 herramientas en total; la IA las seleccionará automáticamente según tus instrucciones.

Proyectos

Requisitos

Errores

Tareas pendientes / Iteraciones / Otros

Recursos MCP

Además de las herramientas (que se invocan activamente), también hay recursos (que la IA puede leer como contexto):

Ejemplos de conversación real

你：幫我看一下有哪些專案
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")
    待辦已建立

Arquitectura y guía del código fuente

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

Diseño clave

• Autenticación automática: Inicia sesión automáticamente al arrancar, refresca el token automáticamente en caso de 401, y vuelve a iniciar sesión si falla.

• Creación en dos pasos: Al crear requisitos/errores, primero se hace POST /add para obtener un número, luego POST /edit para rellenar campos (consistente con el comportamiento del frontend).

• Ningún error provoca caída: Cada herramienta tiene try-catch y devuelve mensajes de error amigables en chino.

• Protección de escritura: Mecanismo WriteGuard protege todas las operaciones de escritura (ver más abajo).

Protección de seguridad (WriteGuard)

La IA podría malinterpretar instrucciones y generar escrituras masivas de datos basura. Todas las operaciones de escritura (create/update) tienen tres líneas de defensa:

1. Modo solo lectura

Prohíbe completamente la escritura; la IA solo puede consultar, no crear/modificar nada:

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

Escenario de uso: Demos, cuando un nuevo miembro no está seguro del comportamiento de la IA, o cuando solo se necesita consultar.

2. Lista blanca de proyectos

Restringe la IA para que solo pueda escribir en proyectos específicos, evitando operar en proyectos incorrectos:

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

Escenario de uso: En producción, solo abrir proyectos de prueba; los miembros del equipo solo operan en sus proyectos asignados.

3. Límite de frecuencia de escritura

Limita el número máximo de escrituras por minuto para evitar que la IA cree muchos elementos en poco tiempo:

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

Cuando se alcanza el límite, la IA recibe un mensaje de error claro:

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

Escenario de uso: Evitar que la IA cree en bucle o malinterprete instrucciones como "crea 100 requisitos".

Combinaciones recomendadas

Desarrollo

# 開發模式（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

Añadir una nueva herramienta

1. Añade o modifica el archivo correspondiente en src/tools/

2. Regístrala con server.tool(name, description, zodSchema, handler)

3. Si es un archivo nuevo, impórtalo en src/index.ts y llama a la función de registro

4. Ejecuta las pruebas para confirmar

// 範例：新增一個 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,
      };
    }
  }
);

Solución de problemas

Stack tecnológico

Cobertura de pruebas

El informe completo de pruebas se encuentra en docs/test-report.md.