convez.ai
MCP ServerDevOps & InfraestruturaAvançado
bimopraksw

Ticketing-Infra-360 MCP Server

bimopraksw/ticketing-infra-360-mcp

Automação de tickets LinkIT360 sem API pública, via headless browser

Ver no GitHub
InicialPluginScore · de 0 a 100

Servidor MCP que integra com a plataforma LinkIT360 para criar e listar tickets de infraestrutura/TI via automação headless com Playwright. Usa autenticação por sessão persistente com login manual único para contornar reCAPTCHA, expondo ferramentas para gerenciar tickets e descobrir schemas de formulários.

Instalação

$npx convez-ai bimopraksw/ticketing-infra-360-mcp

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
0
Forks
0
Acompanhando
0
Saúde
28%
Último commit
há 4 dias
Versão
v0.8.0
Issues abertas
0
Contribuidores
1

Casos de uso

  • Criar tickets de infraestrutura automaticamente a partir de agentes IA
  • Listar e pesquisar tickets/serviços da plataforma LinkIT360
  • Integrar gerenciamento de tickets em fluxos de automação com Claude

Veredito

Solução robusta para quem precisa automatizar tickets em plataforma sem API pública — bem engenheirada com session reuse e login manual smart. Requer máquina com display gráfico e é altamente específica para LinkIT360.

README

A tradução para o português deste README ainda está na fila.

Ticketing-Infra-360 MCP Server

An MCP (Model Context Protocol) server for LinkIT360 Ticketing-Infra on the LinkIT360 platform (https://report.linkit360.com) — create and list IT/Infra tickets from your AI agent.

LinkIT360 exposes no public API — it is a Laravel web application gated behind a login (with reCAPTCHA). This server therefore integrates via headless browser automation (Playwright + Chromium): the user logs in once (solving the captcha in a real browser), the session is persisted and reused, and the server exposes tools to create infra tickets, list/search tickets & services, and inspect/drive the underlying forms.

Status: working & verified end-to-end against the live site — interactive login + session reuse, create_infra_ticket (real ticket created), and the list/discovery tools all confirmed. See INSTALL.md to set it up.


How LinkIT360 works (analysis)

AspectFinding
StackLaravel (PHP), Blade templates
AuthSession-based. POST /login with email + password + CSRF _token. Form uses input[name="email"], input[name="password"], button[type="submit"].
Login CAPTCHAreCAPTCHA v2 ("I'm not a robot" checkbox), sitekey 6LcbQcEeAAAA…. Verified live — invalid captcha is rejected server-side ("Invalid recaptcha").
Public APINone. /api → 404, /api/documentation → 500 (not publicly reachable).
CSRFPresent (_token hidden input / csrf-token meta). Handled automatically because we submit the rendered form.
IntegrationHeadless browser automation, with a one-time manual login to clear the reCAPTCHA.

Because there is no API, the field schema of each record must be discovered from the rendered HTML — that's what the inspect_form tool is for.

Authentication model (important)

reCAPTCHA v2 cannot and must not be solved by automation, so a human clears it once and the session is reused after that. There are two equivalent ways to do that one-time login:

A. From inside your MCP client (recommended) — the login tool

  1. Ask Claude/Cursor to "log in to LinkIT360" (or call the login tool).
  2. A real browser window opens on your machine with credentials pre-filled.
  3. You solve the reCAPTCHA and click Login.
  4. The session is saved and hot-reloaded into the running server — every later tool call just works. No terminal needed.

B. From a terminal — npm run login Same thing, run as a command. Useful for headless setup or first install.

After either, the session cookies live in ~/.linkit360/session.json (the default LINKIT_SESSION_PATH) and are reused for all operations until they expire. When a tool detects the session has expired, it returns a clear message telling you to log in again (it never tries to brute past the captcha). Both flows require a machine with a graphical display (to show the browser window).


Architecture

src/
├── index.ts            # Entry: builds McpServer, stdio transport, graceful shutdown
├── config.ts           # Env loading + validation (zod), URL helpers
├── logger.ts           # Leveled logger -> stderr (never stdout: protocol-safe)
├── browser.ts          # Playwright lifecycle + persistent storageState session
├── auth.ts             # Login flow (drives real form), selector auto-detect, re-login
├── context.ts          # Shared services bundle handed to tools
├── utils/retry.ts      # Exponential-backoff retry
├── tools/
│   ├── index.ts        # Registers all tools
│   ├── session.ts      # check_session, login, logout
│   ├── navigate.ts     # navigate
│   ├── inspect.ts      # inspect_form  (schema discovery)
│   ├── content.ts      # get_page_content
│   ├── screenshot.ts   # screenshot
│   └── records.ts      # submit_form   (create/update writer)
├── prompts/index.ts    # Reusable guided prompts
└── resources/index.ts  # ticketing-infra-360://info resource
tests/
├── smoke.mjs           # MCP protocol handshake + tool listing (no creds)
└── detect-login.mjs    # Live login-form detection (no creds)

Reliability features

  • Persistent session — storageState saved to ~/.linkit360/; log in once, reuse.
  • Auto re-login — every operation calls ensureAuthenticated(); stale sessions transparently re-auth.
  • Retry with backoff — transient navigation/network errors retried (LINKIT_MAX_RETRIES).
  • Timeouts — per-navigation timeout (LINKIT_TIMEOUT_MS).
  • Selector auto-detection — login fields detected across common Laravel conventions, overridable via env.
  • Dry-run writes — submit_form supports dryRun to preview before committing.
  • Protocol-safe logging — all logs go to stderr.

Tools

Typed, high-level tools

ToolPurpose
create_infra_ticketCreate an Infra ticket (POST /ticketing-infra/request). Fully typed: subject, category, company, serviceType (service/project), classification (P0–P4), requestDetail, sentTo[], ccEmail[], country, project, operator, service, files[], attachmentText. See notes below.
list_ticketsList/search tickets for a module (infra/creative/media/legal). Optional global search; returns rows keyed by column header.
list_servicesList/search services from /service/list. Optional global search.
get_field_optionsPropose choices to the user. Returns the available options (value+label) for one or more <select> fields on any page (with optional substring filter). Use when a required dropdown isn't specified — list options, let the user pick. Essential for the option-heavy service form.

create_infra_ticket behavior (learned from the live form's JS validation):

  • Subject is auto-prefixed with "LinkIT - Infra - " (required). Pass a concise 2–3 word summary of the core purpose — e.g. "Change env gameshop" → "LinkIT - Infra - Change env gameshop".
  • serviceType is required — service needs operator+service (for country categories); project needs the project name. If the user didn't specify, ask — the tool won't guess.
  • Dropdowns accept label or value, resolved against the live form (handles select2 widgets).
  • Recipients (sentTo) default to BOTH it.support@linkit360.com and infra@linkit360.com when not specified.
  • Attachment is mandatory. Pass files (JPEG/PNG/PDF/DOC/DOCX/XLS/XLSX, <10 MB), or pass attachmentText (an AI-polished, neat description — core details unchanged) and a PDF is auto-generated. Falls back to requestDetail.
  • dryRun: true fills the form, drives submit to the confirmation dialog to prove validation passes, then cancels — no ticket created. dryRun: false confirms and creates.
  • Submit flows through a SweetAlert "Yes, Create it!" confirmation, handled automatically.

Generic / building-block tools

ToolPurpose
check_sessionIs there a valid authenticated session? (no login)
loginReuse a valid session, or open a real browser window for the user to solve the reCAPTCHA + log in; saves & hot-reloads the session. force to re-login, interactive:false for captcha-free headless login, timeoutSeconds to wait.
logoutClear the persisted session
navigateGo to a path; returns final URL, title, HTTP status
inspect_formDiscover schema — dump every form's fields (name, selector, type, label, required, options, action/method)
get_page_contentVisible text + links + tables of a page (read reports/dashboards)
screenshotPNG screenshot of a page
submit_formGeneric create/update — fill any form's fields by selector and submit; dryRun preview; validation detection. Used for modules without a typed tool yet (creative/media/legal tickets, service create, profile).

Prompts: discover_record_form, create_record_safely. Resources: ticketing-infra-360://info.

Coverage roadmap: create_infra_ticket is the first typed write tool (your priority). Creative/Media/Legal ticket creation and the ~80-field service create form are reachable today via submit_form (+ inspect_form to get selectors) and can be promoted to typed tools the same way infra was.


Setup

New user? See INSTALL.md for a step-by-step install guide (npx or from source) with per-client configuration for Claude Code, Claude Desktop, Cursor, and VS Code.

Requires Node.js ≥ 20.

npm install            # also downloads Chromium via postinstall
cp .env.example .env   # then edit .env with your credentials
npm run build

That's the whole install. The one-time login happens on first use — either by asking your MCP client to "log in to LinkIT360" (the login tool opens a browser), or by running npm run login. After that, everything is automatic.

The user journey (what a new user does)

1. clone + npm install + set .env           (once)
2. add the server to Claude Desktop/Cursor  (once — see Client integration)
3. first action → "log in to LinkIT360"     → browser opens, solve captcha (once)
4. use any tool: "list infra tickets", "create an infra ticket for …"
   → session is reused automatically; re-login only when it expires

Configure .env

LINKIT_BASE_URL=https://report.linkit360.com
LINKIT_EMAIL=you@example.com
LINKIT_PASSWORD=your-password
# optional overrides — see .env.example for the full list
LINKIT_HEADLESS=true
# LINKIT_SESSION_PATH defaults to ~/.linkit360/session.json (absolute); override only if needed
# LINKIT_SESSION_PATH=/Users/you/.linkit360/session.json

Testing & verification

# 1. Protocol smoke test (no credentials) — server starts & speaks MCP
node tests/smoke.mjs

# 2. Live login-form detection (no credentials) — confirms selectors vs real site
node tests/detect-login.mjs

# 3. Live tool test (needs a session from `npm run login`) — reads + dry-run create
node tests/live-tools.mjs

# 4. MCP Inspector (interactive UI) — call tools by hand
npm run inspector

live-tools.mjs verifies list_tickets, list_services, and a create_infra_ticket dry-run (fills the real form but does not submit), against the live site.

Both automated tests pass out of the box:

  • smoke.mjs → advertises all 8 tools, 2 prompts, 1 resource.
  • detect-login.mjs → detects input[name="email"], input[name="password"], button[type="submit"]; confirms POST /login + CSRF.

Phase 2: discover the record schema

Once .env has working credentials:

npm run inspector
# In the Inspector:
#  1) call `login`
#  2) call `inspect_form` with { "path": "/<your-create-page>" }
#  3) read back the fields → that's the record schema

Or from a connected client (Claude Desktop/Cursor), use the discover_record_form prompt. Share the inspect_form output and the typed create_record / update_record wrappers will be wired on top of submit_form.

Creating a record safely

// 1) preview (does NOT submit)
submit_form {
  "path": "/reports/create",
  "fields": [
    { "selector": "input[name=\"title\"]", "value": "June report" },
    { "selector": "select[name=\"category\"]", "value": "Monthly", "kind": "select" }
  ],
  "dryRun": true
}
// 2) commit
submit_form { ...same..., "dryRun": false, "expectSuccessUrl": "/reports" }

Client integration

Claude Desktop

~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "ticketing-infra-360": {
      "command": "node",
      "args": ["/ABSOLUTE/PATH/TO/ticketing-infra-360-mcp/dist/index.js"],
      "env": {
        "LINKIT_BASE_URL": "https://report.linkit360.com",
        "LINKIT_EMAIL": "you@example.com",
        "LINKIT_PASSWORD": "your-password"
      }
    }
  }
}

Cursor

.cursor/mcp.json (project) or global Cursor settings — same shape as above.

VS Code (MCP-enabled extensions / Continue)

Add an MCP server entry pointing command/args at dist/index.js, with the same env. Restart the extension host afterwards.

Build first (npm run build) so dist/index.js exists. Use absolute paths.


Troubleshooting

SymptomCause / Fix
Invalid environment configurationMissing .env values. Copy .env.example → .env, fill LINKIT_*.
Login fails, "still on login page"Wrong credentials, or non-standard form. Set LINKIT_LOGIN_*_SELECTOR from detect-login.mjs output; check the server message in the error.
Could not locate email/password fieldLogin markup differs. Run node tests/detect-login.mjs, then set the LINKIT_LOGIN_*_SELECTOR env vars.
Session keeps expiringServer enforces short sessions. Operations auto re-login; if needed delete ~/.linkit360/session.json and re-run login.
TimeoutsIncrease LINKIT_TIMEOUT_MS; raise LINKIT_MAX_RETRIES. Set LINKIT_HEADLESS=false to watch the browser.
Rate limiting / 429Use the persistent session (default) to minimize logins; add delays between bulk writes.
submit_form reports success:falseRead the returned errors[] (server validation). Re-run inspect_form to confirm field names; required fields may be missing.
Chromium not foundRe-run npx playwright install chromium.
Logs corrupt the clientDon't write to stdout. This server logs only to stderr by design.

Security notes

  • Credentials live in .env (gitignored) or the client's env block. Never commit them.
  • The persisted session in ~/.linkit360/ is a live auth cookie — treat it as a secret. It lives outside the repo by default; if you point LINKIT_SESSION_PATH inside the project, make sure that path is gitignored.
  • Prefer a staging/test account for write operations during development.
Ver o original no GitHub

Bom para

Relacionados