appium-mcp-auth: Instructions file for Claude Code

appium-mcp-auth — project guide

Authentication & authorization for appium-mcp when hosted over SSE / HTTP Stream, built entirely as an appium-mcp plugin. There are no changes to appium-mcp core — this is a hard project constraint (see below).

Golden rule: never modify appium-mcp core

All auth logic lives in this package as a plugin. Do not edit ../appium-mcp/src/* (e.g. create-server.ts, plugin.ts) to add auth. A plugin cannot read HTTP headers, so the credential is passed as a tool argument (authToken), and both authentication and authorization happen in the plugin's beforeCall hook. If a change seems to require touching core, stop and surface it — don't fork core.

Architecture

One process = the full appium-mcp SSE server with this plugin composed in. Users run this package's CLI instead of appium-mcp's bare CLI.

tool call ──► AppiumAuthPlugin.beforeCall(ctx)
                1. authenticate ctx.args.authToken → Identity        (authenticator.ts)
                2. rate-limit per subject                            (rate-limiter.ts)
                3. authorize tool vs Identity.scopes (admin bypass)  (authorizer.ts)
                4. session ownership: sessionId arg must be owned     (ownership.ts)
                5. session-creating tool → per-subject quota
              allow → tool runs   |   deny → error result, tool skipped
            ──► afterCall(ctx, result)
                bind newly-created sessions to caller; release deleted ones

Credential types (dispatched by shape in authenticator.ts):

• ak_<id>_<secret> → static API key (keystore, constant-time) — machines/CI
• st_<secret> → session token minted by auth_login
• <h>.<p>.<s> JWT → OAuth access token verified via JWKS — humans/IDE

File map

File	Responsibility
src/plugin/auth-plugin.ts	The plugin: register (auth_login/whoami/logout), beforeCall, afterCall, lifecycle
src/plugin/create-plugin.ts	Wire deps → createAuthPlugin / createAuthPluginFromEnv
src/auth/authenticator.ts	Dispatch a raw credential to the right verifier → Identity
src/auth/keystore.ts	API-key verify (hashed, timing-safe) + issued session tokens
src/auth/oauth.ts	OAuth JWT validation via jose (JWKS, iss/aud/exp)
src/auth/authorizer.ts	Scope/role checks per tool; admin role bypass
src/auth/ownership.ts	subject ⇄ Appium sessionId registry (multi-tenant isolation)
src/auth/rate-limiter.ts	Per-subject fixed-window limiter
src/auth/keygen.ts	API-key generation (keygen command): bearer + hash + config record
src/core/audit.ts	JSON-line audit events to stderr (never logs credentials)
src/core/config.ts	Env → AuthConfig (loadConfig), sha256Hex
src/core/types.ts	Identity, AuthConfig, ApiKeyRecord, Decision, etc.
src/server/server.ts	buildAuthenticatedServer = createAppiumMcpServer({ plugins:[auth] })
src/server/gateway.ts	Credential-injecting reverse proxy for header-based clients (--gateway)
src/server/http-credential.ts	Pure helpers: read credential from headers, inject authToken into tools/call bodies
src/server/credential-schema.ts	Keep authToken from being stripped by tool schemas before beforeCall runs
src/server/fastmcp-class.ts	Resolve the exact FastMCP class instance that appium-mcp uses (for patching)
src/index.ts	Public package exports
src/cli.ts	Bin entry: keygen command; --gateway (header auth), --httpStream (arg auth), or stdio