Deterministic Model Context Protocol server that gives AI agents structured, verifiable evidence about a real Android/Kotlin/Gradle repository — instead of letting them guess.

The MCP observes. The agent reasons.

The problem

An agent may know what a ViewModel or a Gradle convention plugin generally is, but it can't safely assume which architecture this repository actually uses, which plugins are applied, or whether a proposed change compiles — without either reading the whole repo itself or guessing. This server closes that gap: 25 tools inspect the real project (source, manifests, Gradle output, compiler-parsed symbols) and return what was actually found — never an inferred opinion.

Philosophy

Every tool returns evidence: a file path, a line, a parsed value, a process exit code. Nothing is generated, summarized, or recommended by the server itself — that reasoning stays with the connected agent. See docs/architecture.md for how that boundary is enforced end to end.

Quick start

npm install -g android-corporate-mcp

Add to your MCP client config (Claude Code .mcp.json shown; see docs/configuration.md for every supported client):

{
  "mcpServers": {
    "android-mcp": {
      "command": "android-corporate-mcp"
    }
  }
}

Restart your client, open an Android/Gradle repository, and call a tool:

// tools/call project.inspect { "projectRoot": "/absolute/path/to/your-android-project" }
{
  "status": "success",
  "modules": ["app", "core:network", "feature:home"],
  "settingsFile": "settings.gradle.kts"
}

Full walkthrough: docs/getting-started.md.

What it can do

25 tools across project discovery, Kotlin symbol analysis, Gradle execution, build validation, and security auditing — full contract for each in docs/tools.md.

| Category | Examples | |---|---| | Project & Kotlin | project.inspect, manifest.inspect, symbol.find, symbol.references, module.graph | | Gradle execution | gradle.tasks, gradle.run, tests.run, lint.run, dependencies.inspect | | Architecture & build | architecture.detect, build.validate, staticAnalysis.run | | Android deep inspection | navigation.graph, resource.references, manifest.merge | | Security | proguard.inspect, security.audit |

Compatibility

Speaks standard MCP stdio — no client-specific code. Verified directly on macOS (Apple Silicon) with the local build/JAR/npm launcher; other MCP clients and platforms are expected-compatible but not yet individually confirmed. Full, honestly-graded matrix (tested vs. expected vs. untested) in docs/compatibility.md.

Architecture

flowchart TB
    A["AI Agent<br/>(Claude, Codex, Copilot...)"] -->|MCP stdio| B["Android MCP Server"]
    B -->|reads / executes| C[("Android + Kotlin<br/>repository")]
    C -->|evidence, JSON| B
    B -->|structured evidence| A
    A -->|reasons, decides| D["Implementation"]

    style A fill:#7F52FF,color:#fff
    style B fill:#0D1117,color:#3DDC84,stroke:#3DDC84
    style C fill:#3DDC84,color:#0D1117
    style D fill:#F4B400,color:#0D1117

One process, local stdio transport, no daemon, no persisted state between calls. Full lifecycle, handshake, and a real end-to-end request walkthrough: docs/architecture.md.

Security & local-first

The server runs with the same filesystem and process permissions as the user who launches it, and makes no outbound network call in any of its 25 tools — everything stays on your machine, over local stdio. gradle.run executes Gradle tasks the caller names (validated only for syntax, not restricted to a curated safe list), which is the one tool worth restricting if you connect this server to an agent you don't fully trust. Full breakdown, with no unverifiable "100% secure" claims: docs/security.md.

Documentation

Getting started · Architecture · Tools · Compatibility · Configuration · Security · Limitations · Development · Contributing · Troubleshooting

Contributing

See docs/contributing.md for the real branching model, PR expectations, and how to add a new tool (docs/development.md).

License

package.json declares MIT, but no LICENSE file exists in this repository yet — treat licensing as unresolved until that's added (tracked in docs/contributing.md).