Creatio Case Toolkit

A read-only toolkit for working with Creatio Support cases:

• an MCP server that exposes Creatio's OData API to AI clients (Claude Code, Claude Desktop, …), and

• a local web app that lets non-technical users look up cases by clicking menus — with descriptions, conversation timelines, inline attachments, and optional AI analysis powered by the Claude CLI.

Everything is read-only by construction: the HTTP layer only ever issues GET, there are no create/update/delete paths, and an entity allowlist + row cap keep the blast radius small. Safe to point at production.

Status: early/active. Read-only today; a gated write-back capability (draft & post case updates with human approval) is on the roadmap.

Features

• 🔒 Read-only by design — GET-only client, no write tools, entity allowlist, $top clamp.

• 🧰 MCP server — creatio_query_records, creatio_get_record, creatio_list_allowed_entities.

• 🖥️ Local web app — look up cases by owner, case number, account, or "all recent"; filter by status; choose detail depth.

• 🧵 Rich case detail — HTML-stripped descriptions, merged feed + email timeline, and inline screenshots/attachments proxied from Creatio's FileService.

• ✨ AI analysis (optional) — Summarize & prioritize, Common themes, Next actions, or free-text Q&A over the loaded cases; streamed live via the local Claude CLI (uses your existing Claude login — no API key).

• 📂 Workspace analysis — point the app at up to 3 folders you're working in and get a read-only code analysis of them together, capped at 10 top-level files so it stays fast. Reports are stored under .analysis/ and reused by the bundled skills.

• 🎯 Case-scoped analysis — with a case bound, Analyze for SRxxxxxxxx reads only the files related to that case (searched in subfolders too, ranked by the case's keywords and school code), so a fix starts from the right handful of files instead of the whole folder.

• 🧩 Case → code → fix — the Workspace tab runs in three phases: pick the case, point at the folders, then Plan the fix. You get every change as a before/after diff; nothing is written until you press Apply, and applied edits are left uncommitted for review.

• ⚙️ In-app settings — paste/refresh SSO cookies, base URL, allowlist, row cap; no VS Code required.

• 📡 Live progress — the search streams per-case progress with a percentage bar.

Related MCP server: mcp-sqlserver-readonly

Repository layout

creatio_case_lookup/
  creatio_client.py    Shared read-only OData client (auth, cookies, GET, file download)
  case_lookup.py       Case-lookup query recipes (search, description, timeline, attachments)
  claude_run.py        Generic Claude CLI runner (spawn, NDJSON stream, tool clamping)
  analyze.py           Case AI analysis prompts (isolated run: no tools, no MCP)
  workspace.py         Workspace path validation, file enumeration, .analysis/ store
  case_brief.py        Bound case + stored case brief (.analysis/cases/)
  case_keywords.py     Case text -> sanitized, weighted search terms
  case_files.py        Recursive search + ranking of the files related to a case
  case_scope.py        Keywords + related files for one case
  fix_plan.py          Fix planning (read-only) + reviewed apply (plain Python)
  analyze_workspace.py Read-only workspace analysis (Read/Glob/Grep only)
  workspace_cli.py     CLI over the workspace store, used by the skills
  server.py            Local web app (FastAPI): static hosting + JSON/SSE API
  mcp_server.py        MCP server (thin surface over creatio_client)
  test_auth.py         Standalone credential check
tests/               pytest suite
public/              Web app UI (vanilla HTML/CSS/JS, zero runtime deps)
.claude/skills/      creatio-case-lookup, workspace-analysis, creatio-case-fix
.analysis/           Stored workspace analyses + case briefs (git-ignored local state)
start-app.bat        One-click launcher for the web app (Windows)
.env.example         Copy to .env and fill in

Quick start

Prerequisites:

• Python 3.12+.

• Claude CLI (optional, for the AI features): npm i -g @anthropic-ai/claude-code, then run claude once to sign in.

git clone <your-repo-url> creatio-case-toolkit
cd creatio-case-toolkit
python -m venv .venv
.venv\Scripts\python -m pip install -e ".[login,dev]"   # [login] = browser login, [dev] = pytest
.venv\Scripts\python -m playwright install chromium    # only if you have neither Chrome nor Edge
copy .env.example .env    # then edit .env (see Configuration)
.venv\Scripts\python -m creatio_case_lookup.test_auth   # confirm credentials work (✔ Success)

Run the web app:

.venv\Scripts\python -m creatio_case_lookup.server     # starts the server, opens http://127.0.0.1:3000

On Windows you can just double-click start-app.bat. It finds Python 3.12+, creates the .venv, installs packages (and reinstalls them whenever pyproject.toml changes), creates .env from .env.example if there isn't one, and prints a setup check before starting. The same checklist is the app's first tab, Setup, with a fix for each item. Run the check on its own with .venv\Scripts\python -m creatio_case_lookup.preflight.

The MCP server is already registered — this repo ships a project-scoped .mcp.json, so Claude Code picks it up automatically when opened on this folder (after the .venv exists). Approve the server when prompted.

To register it somewhere else instead:

claude mcp add creatio-readonly -- <repo>\.venv\Scripts\python -m creatio_case_lookup.mcp_server

Configuration

All settings live in .env — the MCP server loads it from the project root itself (next to the creatio_case_lookup package), so its registration needs no env block and both the server and the web app read the same file. Never commit .env — it holds live credentials/cookies (it's git-ignored by default).

Authentication

The client auto-selects a mode based on which vars are set.

• Mode 1 — Forms auth (recommended): a local, least-privilege, read-only Creatio service account (CREATIO_LOGIN + CREATIO_PASSWORD). Re-authenticates automatically on expiry.

• Mode 2 — Cookie auth (SSO tenants): paste a browser session's cookies (.ASPXAUTH, BPMCSRF, BPMLOADER) from DevTools → Application → Cookies. Cookies expire in hours; refresh them in .env or the app's Settings tab and the next query picks them up — no restart needed.

Verify either mode with .venv\Scripts\python -m creatio_case_lookup.test_auth.

Web app

• Lookup tab — choose who (assignee / case number / account / all recent), which statuses, and how much detail (summary, full description, timeline, latest update, extra fields), then Search. Results stream in with a progress bar.

• Attachments — screenshots embedded in descriptions and feed posts render inline (click to enlarge); email attachments appear as thumbnails. Images are streamed through a read-only /api/file proxy restricted to file entities + GUID ids.

• Workspace tab — three phases: 1 pick the case you're working on, 2 point at the folder(s) and run a read-only analysis, 3 plan a fix, review every edit as a diff, and apply it (see below).

• Settings tab — base URL, cookies, allowlist, row cap, plus Test connection.

The server binds to 127.0.0.1 only. Inside this repo it writes your local .env (Settings, Workspace path, bound case) and .analysis/ (workspace reports, case briefs, fix plans and pre-edit backups). The only time it writes outside this repo is when you press Apply on a fix plan you have reviewed — never during an analysis, and never without that approval.

AI analysis

With the Claude CLI installed and logged in, the results view shows an "Analyze with AI" bar — Summarize & prioritize, Common themes, Next actions, or a free-text question, streamed live and rendered as Markdown (copy / download as .md). Tick row checkboxes to analyze a subset; each row also has a "✨ analyze this one" button.

• Enable: npm i -g @anthropic-ai/claude-code, then run claude once to sign in. Uses your Claude subscription — no API key.

• Runs claude -p locally, isolated (no tools, no MCP, empty temp cwd); only the selected cases' text is sent — never your cookies. Uses the model, effort and output style from Settings → Claude settings (saved to .claude/settings.json; default Claude Opus 5.5, claude-opus-5-5, medium effort, Concise). Pick Sonnet 5 or Haiku 4.5 there for cheaper/faster runs.

Workspace analysis

The Workspace tab takes the absolute path of the folder you're working in — plus up to two more via + Add another folder — saves them to .env (effective immediately, no restart), and runs a read-only analysis.

• Several folders, one report. The folders are analyzed together as a single workspace, which is what you want when a fix spans a report template and the shared includes it pulls in. The first folder is the analyzer's working directory; the others are granted explicitly with --add-dir. Adding or removing a folder makes it a different workspace with its own stored report.

• Read-only by construction. The child process is spawned with --tools Read,Glob,Grep, which removes Edit, Write and Bash from its tool schema — not merely from its permissions. Deny rules additionally block .env, *.pem, *.key and SSH keys, so an analysis of this repo cannot read your Creatio cookies. Every tool call is recorded in the report's sidecar, so you can see exactly which files were touched.

• Capped at 10 top-level files in total so a run stays fast. Only files directly in each folder count — no recursion — and the cap applies to the sum across folders. Above the cap the app does not start: it tells you the run will take longer and offers "analyze all N anyway" or a single-file pick. The API enforces the same rule, so a stray request can't kick off a huge run either.

• Excluded automatically: secret-bearing files (.env, keys, certs — counted but never listed), files over 512 KB, non-text files, and the usual build/dependency directories.

• Stored as .analysis/<slug>/analysis.md plus a JSON sidecar (files analyzed, tool calls, model, cost, truncated flag), indexed in .analysis/index.json. The folder is git-ignored local state — safe to delete.

Case-scoped analysis

With a case bound in phase 1, the button reads Analyze for SRxxxxxxxx and analyzes only what that case touches — which is usually a handful of files in a folder of thousands.

• Finding the related files — fast and model-free. The app turns the case's subject, description and recent emails into a short list of keywords (school codes like EP-JAM and file names like EP-JAM-RC.cfm weigh the most), then searches the folders recursively. A folder named after the school code is walked first; files are ranked by path and content matches, with words that appear in almost every file (like "report") counting for little; one hop of <cfinclude> is followed; and anything scoring well below the best match is dropped. The result is capped at the file limit, so there is no over-cap prompt in this mode. On a reports root of 1,700+ school folders this picks the right school's files in a few seconds.

• Preview first. Preview related files shows the chosen files (with why each was picked) — without running Claude. Analyze whole folder instead keeps the classic analysis one click away.

• What the analysis receives from the case. Only the app-extracted keywords (lowercased, reduced to a safe alphabet, max 40 characters each) and the file list the app picked — never the client's wording. The fix plan, as before, does read the case text, with no write tools.

• Stored as .analysis/<slug>/cases/<SR>.md plus sidecar (selected files and reasons). It goes stale when a selected file changes or the case is re-fetched.

The skills use the same logic: python -m creatio_case_lookup.workspace_cli scope <SR> prints the keywords and related files.

Accepted limitation: because the analysis child runs in your folder, that folder's own CLAUDE.md is loaded into its context and cannot be suppressed by any current flag. The folder is one you chose, and --tools bounds the worst case to "read files here and write a misleading report" — but if you analyze a directory you don't trust, read the report with that in mind.

Case → code → fix

The Workspace tab is case-first, because that's how the work actually arrives: a client reports something, you work out which folder it lives in, then you fix it.

1. Case — search by number, owner, account or "all recent" (the same queries as the Lookup tab) and pick one. The app fetches its description, full conversation and attachments and stores them as a brief in .analysis/cases/<SR>.json; the case number goes in .env as CREATIO_WORKSPACE_CASE. Both survive a browser reload and a fresh Claude Code session. Refresh re-pulls the case when it has moved on; Unbind clears it.

   The description is rebuilt into a readable list — support cases are usually numbered asks, and Creatio's HTML arrives flattened — with each ask's continuation lines and indented sub-points kept with it.

   Attachments show as thumbnails (click to enlarge) or open-in-tab links, streamed through the read-only /api/file proxy. An image can be saved straight into a workspace folder (↓ save to folder) when the client wants it used in the template — e.g. a school logo. The filename is editable, since the template usually references a specific name.

   That save is the only write outside this repo besides an approved fix apply, so it is narrow: images only (no .svg — it can carry script), the bytes must actually be that image type (leading bytes are checked, so client-supplied content named logo.png is rejected and a JPEG can't be saved as .png), the target must be a configured folder, the client-supplied name is reduced to a bare filename, 10 MB cap, and replacing an existing file needs a second confirm and copies the original to .analysis/assets/ first. Listing them needs CaseFile in CREATIO_ALLOWED_ENTITIES; without it the brief records a caveat instead of failing. Their contents are not read when planning a fix — the planner is given the filenames only, so a logo's exact colours still have to come from the case text.

2. Working directory — the folders and their read-only analysis, as described above: case-scoped when a case is bound, whole-folder otherwise.

3. Fix — press Plan the fix. A read-only pass reads the case, the stored analysis (the case-scoped one when it exists) and the relevant files, then shows you each proposed change as a before/after diff with its reasoning, risks and what it does not fix. Nothing has touched disk at this point. Press Apply and the edits are written and left uncommitted and unstaged so you review the diff yourself. Originals are backed up first, so it's reversible even outside git.

   The review also breaks the case into what the client actually asked for — using the case's own numbering where it has any — marks each ask addressed, partly addressed or not addressed, and tags every edit with the ask it serves. So you can check the plan against the client's email rather than inferring intent from a diff, and see at a glance which parts were left alone.

   An applied plan stays on screen as a read-only record of what it changed, and can't be applied twice — press Plan the fix again for a fresh one.

   Those addressed labels are the model's own claim, not something the app can verify. On the default Opus model they hold up — an ask needing a capability the code doesn't have comes back not addressed. Weaker/cheaper models over-claim: Haiku marked "add a PDF export button" as addressed and proposed a button that wouldn't do it. If you set CREATIO_APP_MODEL to something cheaper, treat the coverage labels as a prompt to check, not an answer.

The phases are softly ordered — phase 2 works with no case bound, so you can still just analyze a folder. Phase 3 stays disabled, naming what's missing, until a case, folders and a stored analysis all exist.

How the fix button stays safe. Case descriptions and emails are prose written by clients and third parties, so the model that reads them is given no write tools at all — Read, Glob and Grep are the only things in its schema, with no Bash, no WebFetch and no WebSearch. It can only propose a structured list of edits. The app applies them, and before writing anything it re-checks that each file is one it is allowed to edit — a top-level source file of a configured folder, or one of the files the case-scoped analysis selected in a subfolder — and that the "before" text still matches exactly once. So the worst a malicious instruction buried in a case could achieve is a bad patch — one you see as a diff, that can't reach a file outside your workspace, that can't execute or phone home, and whose original is backed up.

Apply is all-or-nothing: if any file changed between planning and approval, nothing is written and you re-plan. Plans, and the originals they replaced, are kept under .analysis/fixes/<plan id>/.

What the folder setting does and does not bound. It bounds edits exactly — only a top-level source file of a configured folder, or a file the case-scoped analysis selected inside one, can be written. It does not bound reads: Glob and Grep take absolute paths, so the planning pass can and does read shared code elsewhere on disk (tracing a report template back into ReportCardRoot, say) — everything except the denied .env, key and certificate patterns. That is usually what you want, since a fix often depends on an include outside the folder. The consequence to know: a plan may propose an edit to a file it could read but cannot write, and that edit shows as can't apply with a note to re-run the case analysis so it's selected, or add the folder in phase 2, and re-plan.

The in-app button needs no setup. The creatio-case-fix skill remains available for when you want to work a case through conversationally — pushing back on the diagnosis, asking for alternatives — rather than accepting or rejecting a diff. Run /creatio-case-fix in Claude Code from this repo; because the Creatio tools are project-scoped here while your files live elsewhere, it may ask you to /add-dir <workspace path> first, and it checks that before spending effort on a recommendation.

Bundled skills

Three skills in .claude/skills/ drive these workflows from a Claude Code conversation:

The skills and the app share one implementation of the cap rule and the artifact schema via python -m creatio_case_lookup.workspace_cli, so reports from either side are interchangeable.

Because the Creatio MCP server is project-scoped in .mcp.json, creatio-case-fix needs Claude Code running in this repo, while the files it edits usually live elsewhere. If it can't read your workspace, run /add-dir <workspace path> (or start with --add-dir) and retry.

MCP server

Registered via the project-scoped .mcp.json in this repo — config comes from .env, so no env block is needed:

{
  "mcpServers": {
    "creatio-readonly": {
      "type": "stdio",
      "command": ".venv/Scripts/python",
      "args": ["-m", "creatio_case_lookup.mcp_server"],
      "env": {}
    }
  }
}

Requires the project's .venv (see Quick start). Anything set in an env block would take precedence over .env, since .env loading never overrides vars already in the process environment.

Foreign keys like OwnerId/AccountId/StatusId are not filterable — filter through navigation paths (Owner/Id, Account/Id, Status/Name). See CASE-QUERY-REFERENCE.md for the full query recipes and gotchas.

Security & data handling

• Read-only: the client issues HTTP GET only; there is no write path to Creatio anywhere in the codebase.

• Local & single-user: the web app binds to 127.0.0.1, with no app-level auth by design.

• Secrets stay local: cookies/credentials live in .env (git-ignored) and are masked in the UI; AI analysis receives only case text, never cookies.

• Bounded reach: entity allowlist + $top clamp; the file proxy is limited to a fixed set of file entities and GUID ids.

• Workspace analysis is read-only too: the analysis child gets --tools Read,Glob,Grep, which removes Edit/Write/Bash from its tool schema, plus deny rules for .env, keys and certificates. --safe-mode and --setting-sources user stop the analyzed folder's own .claude/settings.json hooks from running. Every tool call is recorded in the report sidecar.

• Applying fixes is gated on you: both routes — the Workspace tab's Plan the fix and the creatio-case-fix skill — propose a change, wait for explicit approval, and leave the edits uncommitted. Nothing is ever committed, staged or pushed for you.

• The model that reads case text never holds a write tool: planning runs with --tools Read,Glob,Grep and no Bash/WebFetch/WebSearch, and returns a structured edit list. The app applies it, re-verifying that every target is a top-level source file of a configured folder (or a file the case-scoped analysis selected inside one) and that each "before" string still matches exactly once. Apply is all-or-nothing, and originals are backed up under .analysis/fixes/.

Roadmap

• ✍️ Write-back (Stage 3): draft case replies / status updates with AI, then post them to Creatio on explicit human approval, and verify the write succeeded. This is the planned next step and will be gated, audited, and opt-in — the read-only default stays.

• OAuth 2.0 client-credentials auth for unattended SSO use.

• Pagination past the 50-row cap in the UI; attachment-count badges.

• Optional ActivityFile inline email images.

Agentic maturity: today the toolkit is Stage 2 — Multi-Step (multi-step, multi-tool, read-only "generate but don't run"); the in-app Analyze feature is Stage 1 — Guided Task. Write-back is what moves it into Stage 3 — Autonomous Workflow.

Commands

Run each with .venv\Scripts\python -m <module>:

Development

• Code lives in creatio_case_lookup/; tests in tests/ (pytest, one file per module). Everything network- or subprocess-bound is async; pure logic is plain functions.

• The browser UI in public/ is plain HTML/JS with no build step. Its contract with server.py — routes, JSON keys (camelCase), SSE event names — must change on both sides together.

• On-disk formats under .analysis/ (reports, sidecars, briefs, plans) keep camelCase keys so existing stored data stays readable.

License

Add a license (e.g. MIT) before publishing.