Skip to main content
Glama
README.md
# App Analysis MCP

A local MCP server for understanding applications, investigating bugs, and planning fixes with evidence.

App Analysis MCP brings [REA](https://github.com/morluto/rea), [Craft Anything](https://github.com/storytold/craft-anything), and source analysis tools into one investigation. Your MCP client handles reasoning; the server collects structured observations, runs authorized checks, and keeps the original evidence available.

## What you can do

- Understand functions with Tree-sitter AST queries and syntactic call relationships.
- Combine language-specific linting, local Semgrep rules, Git history, crash stacks, and test results.
- Detect project languages and available checks before choosing an analysis workflow.
- Read compact summaries or retrieve the complete recorded evidence with provenance.
- Distinguish hypotheses, source-reviewed findings, and reproduced failures.
- Hand an evidence-linked diagnosis to Craft Anything for a coding agent to continue.

The server exposes **14 tools**. AST, source inspection, Git, and log parsing work without either backend. REA and Craft are started only when requested. A Craft handoff saves a repair brief; the connected coding agent performs subsequent code generation and editing.

## Quick start

The core requires **Node.js 22 or newer** and npm. Git is needed for history analysis and backend checkout. The setup helper and project-command execution require macOS/Linux. Real backend integration has been verified on macOS arm64; Linux backend integration has not been verified.

```sh
git clone --depth 1 https://github.com/tanjialin-labs/app-analysis-mcp.git
cd app-analysis-mcp
npm ci
npm run check
npm test
```

Generate the MCP configuration for your actual installation path:

```sh
# JSON for clients using the mcpServers format
npm run config --silent

# TOML for Codex
npm run config --silent -- --codex
```

Merge the generated entry into your client's existing configuration. It points directly to Node and `bin/server.mjs` using absolute paths. The server uses **stdio**, has no web interface, and reserves stdout for the MCP protocol. Restart the client connection after changing the installation or configuration.

For Codex, the generated block belongs in `~/.codex/config.toml`. Keep your existing settings and other MCP entries; avoid adding a duplicate `app_analysis` entry. The generated tool timeout is 300 seconds. If you intentionally run longer checks, increase the client's timeout as well as the tool's `timeout_ms`.

Then ask your client:

> Use app_analysis to inspect /absolute/path/to/my-project. Create a debug case, identify the project and available checks, inspect the relevant function, and report evidence-backed findings. Ask before executing project code unless I have already authorized it.

To enable REA and Craft, follow [Backend setup](docs/backends.md). To inspect their readiness:

```sh
npm run doctor
```

`doctor` exits with status 1 when either backend is missing. That does not prevent the independent source-analysis tools from working.

## Tools

| Tool | Purpose |
| --- | --- |
| `workbench_status` | Inspect local runtime readiness, page through investigations, and list configured checks. |
| `workbench_create_case` | Create a `reverse`, `debug`, or `optimize` investigation with a target, goal, and optional source root. |
| `workbench_triage` | Identify project languages, manifests, available adapters, and named checks; select an appropriate route. |
| `workbench_discover_tools` | Search a live REA or Craft catalog and retrieve an exact tool's input schema. |
| `workbench_call` | Invoke an allowed upstream tool and retain its original response and session identity. |
| `workbench_inspect_source` | List files, search literal text, or read source with line numbers. |
| `workbench_analyze` | Run AST, lint, Git, Semgrep, stack symbolization, or log analysis through one structured interface. |
| `workbench_investigate_crash` | Collect bounded evidence for a selected function and files, with explicit coverage gaps. |
| `workbench_run_check` | Execute an authorized, named project check and retain logs, exit status, and parsed results. |
| `workbench_read_record` | Read summaries, typed items, JSON Pointer fields, or paged original JSON. |
| `workbench_record_finding` | Save a caller-authored diagnosis, verification level, recommendations, and evidence references. |
| `workbench_handoff_to_craft` | Validate a saved finding and write its diagnosis and repair/test request to Craft. |
| `workbench_report` | Generate a Markdown report with findings, evidence, coverage, and limitations. |
| `workbench_close_case` | Close backend sessions and release subprocesses while retaining evidence. |

The server also provides the `reverse_app`, `debug_app`, and `optimize_app` prompts.

## Analysis adapters

Select an adapter with `workbench_analyze.analysis.kind`:

| Kind | Capability | Requirements and limits |
| --- | --- | --- |
| `ast` | Function ASTs, Tree-sitter queries, and syntactic call candidates. | Included WASM grammars for Python, C/C++, Go, JS/TS/TSX, Rust, Java, Swift, and Objective-C. No whole-program type resolution or runtime call graph. |
| `git` | `diff`, `blame`, and `log`. | Local Git repository; shallow clones have limited history. |
| `lint` | Ruff, clang-tidy, golangci-lint v2, ESLint, or SwiftLint. | Install the relevant tool separately. ESLint requires execution authorization because it can load executable configuration. |
| `semgrep` | Search for candidate bug patterns using local rules. | Optional Semgrep; three small bundled rules, or a caller-selected rule file inside the source root. No remote rule registry is fetched. |
| `symbolize` | Parse stacks and map native addresses to source locations. | Native lookup needs LLVM symbolizer or addr2line, matching symbols, and an explicit load bias for runtime addresses. |
| `logs` | Parse compiler diagnostics, JUnit, Jest/Vitest JSON, pytest JSON reports, Go test JSONL, and text stacks. | Input text or a local log file. Unknown formats and unparsed lines remain explicit. |

Missing tools, malformed scanner output, and skipped analysis are reported explicitly. A static warning is a candidate issue; absence of warnings does not prove correctness. See [Configuration and adapter setup](docs/configuration.md).

## Example: investigate a crashing function

Call `workbench_create_case`:

```json
{
  "mode": "debug",
  "target": "/absolute/path/to/project",
  "source_root": "/absolute/path/to/project",
  "goal": "Find why countItems crashes on missing input",
  "expected": "Return zero for missing input",
  "actual": "TypeError while reading length",
  "allow_execution": true
}
```

Set `allow_execution: true` only when you authorize running this project's checks. Use the returned UUID to call `workbench_triage`, then `workbench_investigate_crash`:

```json
{
  "case_id": "<returned-case-uuid>",
  "function_name": "countItems",
  "target_file_filter": ["src/items.js"],
  "timeout_ms": 60000,
  "max_lines": 200
}
```

The workflow chooses available adapters, records each result, and explains skipped capabilities. The first file is used for function selection and blame; additional files provide context. `include_backends: true` requests supplementary REA/Craft analysis where applicable. Ordinary source code is not treated as a compiled binary.

Next, the client reads evidence, considers alternative explanations, and runs a check by an exact name returned from triage, such as `npm-test:.` or `swift-test:Packages/Core`. It records a finding, optionally hands it to Craft using the returned `finding_id`, writes a report, and closes the case.

## Evidence and limits

- Tool results are JSON. Original responses, command output, arguments, timestamps, identities, and hashes remain in local evidence records.
- `workbench_read_record` defaults to `view: "summary"`; use `items`, `field`, or `raw` for detail. Follow `next_offset` when present.
- Location grouping preserves separate observations and references. It does not infer a shared root cause.
- A `reproduced` finding requires a completed project-check record and reproduction details. Its causal interpretation remains the caller's responsibility.
- Craft handoffs use the saved finding and revalidate its evidence hashes. Cross-case references and changed evidence are rejected.
- Analysis accepts at most 10 exact relative file paths, defaults to 30 seconds, and has a 120-second maximum. `max_lines` bounds returned rows/nodes, with truncation and coverage reported.
- Named project checks support up to 600 seconds. Default storage budgets are 16 MiB per record and 256 MiB per case, with at most 3 active cases. Backend-owned databases are outside that disk budget.
- Closing a case retains its records. Restarting the server does not restore old upstream sessions or make their IDs valid in new sessions.

Evidence can contain source code and logs. It stays under `.workbench/` by default; your MCP client controls what it sends to its model provider. Review evidence before sharing it. Source inspection does not execute the target, but authorized checks and executable linter configuration do. This server is not an operating-system sandbox.

## Development and verification

```sh
npm run check
npm test

# Optional: requires ready REA/Craft backends plus Ruff and Semgrep
npm run test:integration
```

The default suite is self-contained and does not need backend installations, credentials, or a production application. It covers MCP contracts, source analysis, evidence integrity, project checks, failure handling, resource limits, and backend checkout preservation.

The optional integration test uses the deliberately broken [crash demo](examples/crash-demo/README.md). It exercises real REA/Craft, Tree-sitter, Ruff, Semgrep, JUnit parsing, a failing reproducer, a Craft handoff, reporting, and cleanup. Its receipt is written to `.workbench/last-integration.json`. Real native decompilers, browsers/devices, paid coding agents, and all optional linters are outside that test's coverage.

See [CONTRIBUTING.md](CONTRIBUTING.md) for contribution and verification guidance.

## Upgrading from 0.1

- `workbench_handoff_to_craft` now takes `finding_id`, rather than independent diagnosis, verification, and evidence fields. Record the finding first.
- `workbench_read_record` now defaults to a summary. Specify `view: "raw"` for the previous text-pagination behavior. Existing record IDs and stored evidence remain readable.

## License and acknowledgements

App Analysis MCP is released under the [MIT License](LICENSE). REA and Craft Anything remain separate upstream projects with their own licenses. This repository contains the integration layer, not bundled upstream source or binaries. See [THIRD_PARTY.md](THIRD_PARTY.md).

TDQS

A3.6/5.0

Scored across 14 tools

Disambiguation4/5

Tools map cleanly onto a case lifecycle (status, create, triage, discover, call, inspect, run, read, record, report, close) with distinct purposes. The main overlap is workbench_analyze vs workbench_investigate_crash, since the crash tool bundles the same AST/linter/Semgrep/git primitives as analyze; workbench_call also acts as a generic escape hatch that could tempt use where run_check or analyze is intended. Descriptions largely resolve these boundaries.

Naming Consistency4/5

All 14 tools share a workbench_ prefix and snake_case, with verbs mostly leading (create_case, run_check, record_finding, close_case). A few names are noun-only or ambiguous as verb/noun (workbench_status, workbench_report, workbench_triage), a minor deviation from the verb_noun pattern. Still highly predictable and scannable.

Tool Count5/5

14 tools sit in the well-scoped 3-15 range and each covers a distinct stage of an investigation workflow rather than duplicating surface. Nothing appears redundant or filler, and the count reflects the genuine breadth of triage, evidence capture, execution, and reporting.

Completeness4/5

Full case lifecycle is covered: creation, triage, source inspection, check execution, evidence reading, finding recording, reporting, handoff, and close. Gaps are minor: there is no way to update or supersede a recorded finding, and no explicit resume/reopen operation for a closed case. Agents can work around these by creating new cases or records, but the surface is not entirely dead-end free.

Maintenance

ActivityMaintained
ResponsivenessNo recent community issues