Flutter Analysis Engine (MCP)

Local-first Model Context Protocol interface over a reusable Flutter Analysis Engine. The MCP server is one front end; the product is deterministic static analysis (facts → findings → insight) grounded in official Flutter/Dart knowledge cloned via git. No GitHub API and no LLM inside the server.

Status

Related MCP server: Atlas

Supported repositories

Current (Phase 4):

• flutter/flutter — framework source

• flutter/packages — official packages

• flutter/engine — engine source

• dart-lang/sdk — Dart SDK

• dart-lang/site-www — Dart language site

• flutter/samples — official samples

• flutter/website — official documentation

Also indexed as first-class knowledge: CHANGELOGs, migration guides, and widget tests.

Git is only used to clone/pull these official trees. There is no GitHub API in normal operation.

Requirements

• Node.js 20+

• git on PATH

• Recommended: Dart SDK 3+ (full-fidelity AST via parser/; without it, analysis falls back to heuristics with reduced confidence)

Setup

cd flutter-knowledge-mcp
npm install
npm run build

Optional Dart helper (strongly recommended for project analysis):

cd parser && dart pub get && cd ..

Configuration (config.json):

{
  "repositoriesRoot": "./repos",
  "indexPath": "./data/knowledge.sqlite",
  "indexOnUpdate": true
}

Paths resolve relative to the config file. Override with:

export FLUTTER_KNOWLEDGE_CONFIG=/absolute/path/to/config.json

Cursor integration

{
  "mcpServers": {
    "flutter-knowledge": {
      "command": "node",
      "args": ["/ABSOLUTE/PATH/TO/flutter-knowledge-mcp/dist/index.js"]
    }
  }
}

MCP tools

Repository

Search & widgets

Docs, examples & intended behavior

Project analysis (insight-first, session-aware)

Token-efficient workflow:

1. review_project({ path }) → health, top risks/strengths/actions, sessionId

2. analyze_architecture({ sessionId }) / analyze_* → slim category views (no rescan)

3. explore_finding({ sessionId, findingCode }) / explain_finding → drill into one issue

Full reports are stored under data/analysis-sessions/. Follow-up tools read the cache.

Confidence model

Every finding includes confidence (0–1) and source (dart_analyzer | heuristic | filesystem | pubspec | import_graph).

review_project leads with an Analysis Summary:

• Engine identity (Flutter Analysis Engine v0.7.0)

• AST source (dart_analyzer or heuristic)

• Coverage (full / partial / none)

• Aggregate confidence

• Recommendation to install Dart SDK when falling back

Each category score includes positive/negative contributors, weight, and confidence. Findings carry structured evidenceItems, related finding codes, and knowledge-resolved official references when the index has matches.

Official references stay as supporting evidence, not the primary answer. Insight narratives and explained health scores are the main deliverable.

Engines live under src/analysis/ (ast / engines / insight / metrics / rules / session) and are reusable outside MCP. Handlers orchestrate analyze → cache → slim query.

Typical first-run flow:

1. update_repositories (large first clone — includes engine)

2. Wait for index (or call reindex)

3. review_project → then session-scoped analyze_* / explore_finding / find_intended_behavior

Architecture

Cursor
  └── MCP (stdio) — thin tools/
        └── analysis/  (future flutter-analysis-core)
              ├── ast/          AstAdapter (Dart preferred, heuristic fallback)
              ├── engines/      CodeQuality / State / Architecture
              ├── insight/      Explanation + Recommendation + Health + ReportBuilder
              ├── session/      AnalysisSessionStore + slim summary views
              ├── metrics/      MetricsEngine
              ├── rules/        RuleEngine plugin registry
              ├── project-scanner.ts
              └── official-refs.ts
        ├── repository/     git clone / pull / status
        ├── indexer/        incremental hashing + path classification
        ├── parser/         TS heuristics + Dart analyzer client
        ├── store/          SQLite knowledge store (schema v2)
        ├── search/         IndexedSearchEngine → filesystem fallback
        ├── config/         JSON + zod
        └── server/         DI (tsyringe) + McpServer

Development

npm run test
npm run typecheck
npm run lint
npm run dev

Error model

Tools return structured JSON failures (never raw exceptions), including:

RepositoryNotFound, RepositoryMissing, GitError, SearchFailed, InvalidArguments, ConfigError, IndexError, AnalyzerUnavailable, ProjectNotFound, InternalError.

Logging

Structured JSON on stderr (info / warning / error). stdout is MCP-only.

Roadmap (later)

• Monorepo extract (packages/flutter-analysis-core, CLI, web)

• Additional analyzers (dependency, complexity, performance, accessibility, testing, docs)

• Retire heuristic AST fallback when Dart Analyzer coverage is always available

• Vector embeddings / semantic search

• Optional third-party ecosystems (e.g. FlutterFire)