{"_id":"@ahmetkca/missionplanner-mcp-server","_rev":"4-8710e12c1ac2f9584016dc88b319f275","name":"@ahmetkca/missionplanner-mcp-server","dist-tags":{"latest":"0.2.0"},"versions":{"0.1.0":{"name":"@ahmetkca/missionplanner-mcp-server","version":"0.1.0","keywords":["mcp","ardupilot","mission-planner","mavlink"],"author":{"name":"Ahmet Karapinar"},"license":"MIT","_id":"@ahmetkca/missionplanner-mcp-server@0.1.0","maintainers":[{"name":"ahmetkca","email":"akarapinrar@gmail.com"}],"bin":{"missionplanner-mcp-server":"dist/index.js"},"dist":{"shasum":"978d5ab11918d49cd2ba91eb52be83d007dd01d1","tarball":"https://registry.npmjs.org/@ahmetkca/missionplanner-mcp-server/-/missionplanner-mcp-server-0.1.0.tgz","fileCount":53,"integrity":"sha512-/R2Yi/75XfgmPb3B1K6bKogWyi459DZZtjfiodA1F/5DeBfGaYG700ncpVCY4Wn3OQUM+OkqQMoEoegdeoLf7A==","signatures":[{"sig":"MEUCIFlIVeiXCacN06awFGUI1ZCKkkurPtwUc0ob9q21TSjgAiEAs/c/WugbEM8g35EnOnwAuGIC+6Dq3eCGE5D4EHiDgII=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":72235},"main":"dist/index.js","type":"module","types":"./dist/index.d.ts","gitHead":"975092e49fc31eda9eb5d1ef24ef16c149d1ffe0","scripts":{"dev":"tsx watch src/index.ts","build":"tsc","start":"node dist/index.js","typecheck":"tsc --noEmit","start:http":"node dist/index.js --transport http --port 9990","start:stdio":"node dist/index.js --transport stdio"},"_npmUser":{"name":"ahmetkca","email":"akarapinrar@gmail.com"},"_npmVersion":"11.9.0","description":"MCP server for ArduPilot Mission Planner — exposes vehicle parameters to AI coding agents","directories":{},"_nodeVersion":"24.14.0","dependencies":{"zod":"^4.3.6","@modelcontextprotocol/sdk":"^1.29.0"},"_hasShrinkwrap":false,"devDependencies":{"tsx":"^4.21.0","typescript":"^6.0.2","@types/node":"^25.6.0"},"_npmOperationalInternal":{"tmp":"tmp/missionplanner-mcp-server_0.1.0_1776396892546_0.7688810891980653","host":"s3://npm-registry-packages-npm-production"}},"0.1.1":{"name":"@ahmetkca/missionplanner-mcp-server","version":"0.1.1","keywords":["mcp","ardupilot","mission-planner","mavlink"],"author":{"name":"Ahmet Karapinar"},"license":"MIT","_id":"@ahmetkca/missionplanner-mcp-server@0.1.1","maintainers":[{"name":"ahmetkca","email":"akarapinrar@gmail.com"}],"bin":{"missionplanner-mcp-server":"dist/index.js"},"dist":{"shasum":"066eef9149cb90ebb23b315317751a23b882caca","tarball":"https://registry.npmjs.org/@ahmetkca/missionplanner-mcp-server/-/missionplanner-mcp-server-0.1.1.tgz","fileCount":53,"integrity":"sha512-J8Do12Q2tIvgDZL7/OgdvGTpcbcAUFBJpxDEfRHoxYzZB8l5jMLJMGvrah1OXJOx22q5lhEcALEFXs7VDpLGhA==","signatures":[{"sig":"MEUCIQDHcFOYr+btg9nZmV22j2wcktoikwTF4S6Vuwl3P1k+5QIgMfPmvMIr79C5g6S4Dw3Lw0SLehYLiIdIrxJfFnPlFbk=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":72296},"main":"dist/index.js","type":"module","types":"./dist/index.d.ts","gitHead":"1b365341ec28073336eab32d0e4c6d7ece97b9b0","scripts":{"dev":"tsx watch src/index.ts","build":"tsc","start":"node dist/index.js","typecheck":"tsc --noEmit","start:http":"node dist/index.js --transport http --port 9990","start:stdio":"node dist/index.js --transport stdio"},"_npmUser":{"name":"ahmetkca","email":"akarapinrar@gmail.com"},"_npmVersion":"11.9.0","description":"MCP server for ArduPilot Mission Planner — exposes vehicle parameters to AI coding agents","directories":{},"_nodeVersion":"24.14.0","dependencies":{"zod":"^4.3.6","@modelcontextprotocol/sdk":"^1.29.0"},"_hasShrinkwrap":false,"devDependencies":{"tsx":"^4.21.0","typescript":"^6.0.2","@types/node":"^25.6.0"},"_npmOperationalInternal":{"tmp":"tmp/missionplanner-mcp-server_0.1.1_1776398086872_0.3389145587108766","host":"s3://npm-registry-packages-npm-production"}},"0.1.2":{"name":"@ahmetkca/missionplanner-mcp-server","version":"0.1.2","keywords":["mcp","ardupilot","mission-planner","mavlink","model-context-protocol","ai-agent"],"author":{"name":"Ahmet Karapinar"},"license":"MIT","_id":"@ahmetkca/missionplanner-mcp-server@0.1.2","maintainers":[{"name":"ahmetkca","email":"akarapinrar@gmail.com"}],"homepage":"https://github.com/ahmetkca/missionplanner-mcp-server#readme","bugs":{"url":"https://github.com/ahmetkca/missionplanner-mcp-server/issues"},"bin":{"missionplanner-mcp-server":"dist/index.js"},"dist":{"shasum":"1d961602776deb84f275d1af3965e76cb448393c","tarball":"https://registry.npmjs.org/@ahmetkca/missionplanner-mcp-server/-/missionplanner-mcp-server-0.1.2.tgz","fileCount":42,"integrity":"sha512-k3u/zx41iv6GDxNFa81hbZPFXzRB+LvozBkt8UkYmsMMrrxlpsm9lAXpQD9sChX2FL/BSJQlIowwg4uuUz8paw==","signatures":[{"sig":"MEUCICWTIiRZFk93zFTKpqK/SSDAuaAIb3Sbw6EOUdAifZatAiEA0zunjQAde8qfcWPD/h4M/9RyBazqIwE2ZK+clNwpOoc=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":59011},"main":"dist/index.js","type":"module","types":"./dist/index.d.ts","engines":{"node":">=20"},"gitHead":"44d28996fdce6769f2cd545becb6903423e322e2","scripts":{"dev":"tsx watch src/index.ts","build":"tsc","start":"node dist/index.js","typecheck":"tsc --noEmit","start:http":"node dist/index.js --transport http --port 9990","start:stdio":"node dist/index.js --transport stdio"},"_npmUser":{"name":"ahmetkca","email":"akarapinrar@gmail.com"},"repository":{"url":"git+https://github.com/ahmetkca/missionplanner-mcp-server.git","type":"git"},"_npmVersion":"11.9.0","description":"MCP server for ArduPilot Mission Planner — exposes vehicle parameters to AI coding agents","directories":{},"_nodeVersion":"24.14.0","dependencies":{"zod":"^4.3.6","@modelcontextprotocol/sdk":"^1.29.0"},"_hasShrinkwrap":false,"devDependencies":{"tsx":"^4.21.0","typescript":"^6.0.2","@types/node":"^25.6.0"},"_npmOperationalInternal":{"tmp":"tmp/missionplanner-mcp-server_0.1.2_1776571150030_0.31931337881580846","host":"s3://npm-registry-packages-npm-production"}},"0.2.0":{"name":"@ahmetkca/missionplanner-mcp-server","version":"0.2.0","description":"MCP server for ArduPilot Mission Planner — exposes vehicle parameters to AI coding agents","main":"dist/index.js","type":"module","bin":{"missionplanner-mcp-server":"dist/index.js"},"scripts":{"dev":"tsx watch src/index.ts","build":"tsc","start":"node dist/index.js","start:stdio":"node dist/index.js --transport stdio","start:http":"node dist/index.js --transport http --port 9990","typecheck":"tsc --noEmit"},"keywords":["mcp","ardupilot","mission-planner","mavlink","model-context-protocol","ai-agent"],"author":{"name":"Ahmet Karapinar"},"license":"MIT","repository":{"type":"git","url":"git+https://github.com/ahmetkca/missionplanner-mcp-server.git"},"bugs":{"url":"https://github.com/ahmetkca/missionplanner-mcp-server/issues"},"homepage":"https://github.com/ahmetkca/missionplanner-mcp-server#readme","engines":{"node":">=20"},"dependencies":{"@modelcontextprotocol/sdk":"^1.29.0","zod":"^4.3.6"},"devDependencies":{"@types/node":"^25.6.0","tsx":"^4.21.0","typescript":"^6.0.2"},"gitHead":"d762c13338566a69255b7ded0814aa30bf7faeb6","types":"./dist/index.d.ts","_id":"@ahmetkca/missionplanner-mcp-server@0.2.0","_nodeVersion":"24.14.0","_npmVersion":"11.9.0","dist":{"integrity":"sha512-qzbuQFL6YNZ3f1LsOnvHFw0JEy38X9rGRYpJVFlyXrsGiJzp6tNT390n9nNiM4JwWHgvnLj0wrCqQk2TbpCSJg==","shasum":"927f324ce479da3540d9df771d64249f6756e009","tarball":"https://registry.npmjs.org/@ahmetkca/missionplanner-mcp-server/-/missionplanner-mcp-server-0.2.0.tgz","fileCount":46,"unpackedSize":69321,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIQDLXac24aCYOB8ER8Yfc7/ZkEUeYPoGgyCg/vY6Hpg6oAIgHhhqq8vEo8/4g/bRVwQvI9mF5Jhh8WnQCCLJZIYtyUk="}]},"_npmUser":{"name":"ahmetkca","email":"akarapinrar@gmail.com"},"directories":{},"maintainers":[{"name":"ahmetkca","email":"akarapinrar@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/missionplanner-mcp-server_0.2.0_1787013540618_0.6857956549804924"},"_hasShrinkwrap":false}},"time":{"created":"2026-04-17T03:34:52.476Z","modified":"2026-08-18T00:39:00.911Z","0.1.0":"2026-04-17T03:34:52.688Z","0.1.1":"2026-04-17T03:54:47.027Z","0.1.2":"2026-04-19T03:59:10.158Z","0.2.0":"2026-08-18T00:39:00.778Z"},"bugs":{"url":"https://github.com/ahmetkca/missionplanner-mcp-server/issues"},"author":{"name":"Ahmet Karapinar"},"license":"MIT","homepage":"https://github.com/ahmetkca/missionplanner-mcp-server#readme","keywords":["mcp","ardupilot","mission-planner","mavlink","model-context-protocol","ai-agent"],"repository":{"type":"git","url":"git+https://github.com/ahmetkca/missionplanner-mcp-server.git"},"description":"MCP server for ArduPilot Mission Planner — exposes vehicle parameters to AI coding agents","maintainers":[{"name":"ahmetkca","email":"akarapinrar@gmail.com"}],"readme":"# @ahmetkca/missionplanner-mcp-server\n\n> An [MCP](https://modelcontextprotocol.io) server that gives AI coding agents (Claude Code, Codex, etc.) structured, live context about [ArduPilot Mission Planner](https://github.com/ArduPilot/MissionPlanner) — starting with the full vehicle parameter set.\n\n**Status:** pre-1.0, MVP, read-only. Localhost-only, single-vehicle, no auth. See [Roadmap](#roadmap).\n\n---\n\n## What it does\n\nWhen Mission Planner is connected to a vehicle (via COM/TCP/UDP), this server lets an AI agent:\n\n- Ask whether MP is connected, to which vehicle, and with what firmware.\n- List the full parameter set (1000+ params on a typical vehicle) with values and MAVLink types.\n- Look up a single parameter by name with **full pdef metadata** — description, units, allowed values, bitmask definitions, range, reboot-required flag, and more.\n- Search parameters by keyword across names, display names, and descriptions.\n\nThe metadata is whatever MP already has cached locally in its pdef database — no extra downloads, no parsing in this process.\n\n---\n\n## How the pieces fit together\n\n```\n┌──────────────────────────┐      ┌─────────────────────────────┐      ┌─────────────────┐\n│  Mission Planner         │      │  @ahmetkca/missionplanner-  │      │  AI coding      │\n│  (with MCP bridge)       │◄────►│  mcp-server                 │◄────►│  agent          │\n│                          │      │                             │      │                 │\n│  HTTP  127.0.0.1:9999    │ HTTP │  stdio (default)            │  MCP │                 │\n└──────────────────────────┘      │  or Streamable HTTP on 9990 │      └─────────────────┘\n                                  └─────────────────────────────┘\n```\n\nTwo moving parts you need to run:\n\n1. **Mission Planner** with the HTTP bridge compiled in. This lives on a fork at [`ahmetkca/MissionPlanner`](https://github.com/ahmetkca/MissionPlanner) on branch `feat/mcp-bridge`.\n2. **This MCP server.** Installed from npm, spawned by your agent (stdio) or run separately (HTTP).\n\n---\n\n## Requirements\n\n- Node.js 20+ (tested on Node 24).\n- A running Mission Planner built from [`ahmetkca/MissionPlanner@feat/mcp-bridge`](https://github.com/ahmetkca/MissionPlanner/tree/feat/mcp-bridge). The bridge listens on `127.0.0.1:9999` from MP startup — no extra config needed.\n- Whatever MCP-capable agent you want to use (this repo has been tested with [Claude Code](https://www.claude.com/product/claude-code)).\n\nYou do **not** need to connect MP to a vehicle for the server to start — the `mp_status` tool will just report `connected: false`. The read tools will start returning live data as soon as MP finishes the parameter download after connecting.\n\n---\n\n## Install & configure\n\n### Claude Code\n\nAdd this to your `~/.claude.json` under `mcpServers`.\n\n**macOS / Linux:**\n\n```json\n{\n  \"mcpServers\": {\n    \"missionplanner\": {\n      \"command\": \"npx\",\n      \"args\": [\"--yes\", \"@ahmetkca/missionplanner-mcp-server\"]\n    }\n  }\n}\n```\n\n**Windows** (requires `cmd /c` — see [Windows gotchas](#windows-gotchas) below):\n\n```json\n{\n  \"mcpServers\": {\n    \"missionplanner\": {\n      \"command\": \"cmd\",\n      \"args\": [\"/c\", \"npx\", \"--yes\", \"@ahmetkca/missionplanner-mcp-server\"]\n    }\n  }\n}\n```\n\nRestart Claude Code. Run `/mcp` — the server should show as connected. Ask: *\"What's the status of Mission Planner?\"* or *\"List all ARSPD parameters.\"*\n\n### Other MCP clients\n\nAny client that speaks the Model Context Protocol and can spawn a stdio server should work. Point it at `npx --yes @ahmetkca/missionplanner-mcp-server`.\n\nFor clients that prefer an HTTP endpoint, run the server manually (see [HTTP mode](#http-mode)) and point your client at `http://127.0.0.1:9990/mcp`.\n\n---\n\n## Tools\n\n| Tool | Description |\n|---|---|\n| `mp_status` | Is MP running? Connected? Which vehicle and firmware? Is the bridge API version compatible with this server? |\n| `list_params(prefix?, limit?, cursor?)` | Browse params with optional name-prefix filter and opaque-cursor pagination. Returns lightweight entries (name, value, type) — no metadata. |\n| `get_param(name)` | Full pdef metadata for a single parameter. Case-sensitive, UPPER_SNAKE_CASE. |\n| `search_params(query)` | Keyword search across parameter names, display names, and descriptions. Returns up to 25 results with full metadata, ranked by match quality. |\n\n## Resources\n\n| URI | Description |\n|---|---|\n| `ardupilot-missionplanner://vehicle/params` | Full lightweight param list (same shape as `list_params` with no filter, unpaginated). |\n| `ardupilot-missionplanner://vehicle/params/{name}` | Resource template — one param with full metadata. Registers `list` and `complete` callbacks so agents can browse and autocomplete. |\n\n---\n\n## Run modes\n\nThe server supports two transports, selected via `--transport`.\n\n### stdio (default)\n\n```bash\nnpx @ahmetkca/missionplanner-mcp-server\n# equivalent to:\nnpx @ahmetkca/missionplanner-mcp-server --transport stdio\n```\n\nOne instance per agent session. The agent spawns it as a child process. This is the recommended default.\n\n### HTTP mode\n\n```bash\nnpx @ahmetkca/missionplanner-mcp-server --transport http --port 9990\n```\n\nRuns a [Streamable HTTP](https://modelcontextprotocol.io/specification/2025-03-26/basic/transports#streamable-http) server on `127.0.0.1:9990/mcp`, with a `/health` endpoint for liveness checks. One instance can serve multiple agents and survives agent restarts. Useful for:\n\n- Debugging with [`@modelcontextprotocol/inspector`](https://github.com/modelcontextprotocol/inspector).\n- Sharing a warmed-up process (bridge already validated, no startup latency) across multiple agent sessions.\n\n### Flags\n\n| Flag | Default | Purpose |\n|---|---|---|\n| `--transport <stdio\\|http>` | `stdio` | Transport mode |\n| `--port <n>` | `9990` | Port for HTTP mode |\n| `--bridge-url <url>` | `http://127.0.0.1:9999` | Where the MP HTTP bridge is listening |\n\n---\n\n## Windows gotchas\n\nThree things tripped us up during initial rollout, all documented here so future-you doesn't rediscover them:\n\n1. **You must use `cmd /c npx ...` in your agent config.** Claude Code on Windows does not resolve `.cmd` shims through `PATHEXT` when spawning a command directly. Wrapping in `cmd /c` works.\n2. **You must use `--yes` with `npx`.** Otherwise the first invocation prompts \"Ok to proceed?\" on stdout and corrupts the JSON-RPC stream.\n3. **`.js` files must have a `#!/usr/bin/env node` shebang** for npm to generate a proper `.cmd` shim on Windows. This is handled inside this package; listed here only in case you fork or vendor the code.\n\nDiagnosis tip: run Claude Code with `--debug` to get stderr from the spawned MCP server in the debug log. The actual failure message is usually hiding there.\n\n---\n\n## Development\n\n### Local setup\n\n```bash\ngit clone https://github.com/ahmetkca/missionplanner-mcp-server.git\ncd missionplanner-mcp-server\nnpm install\nnpm run build\n```\n\n### Scripts\n\n| Script | What |\n|---|---|\n| `npm run dev` | `tsx watch` on `src/index.ts` for fast iteration |\n| `npm run build` | `tsc` → emits `dist/` |\n| `npm run typecheck` | `tsc --noEmit` |\n| `npm run start:stdio` | Run the built server in stdio mode |\n| `npm run start:http` | Run the built server in HTTP mode on 9990 |\n\n### Point your agent at the local build\n\nReplace the `npx` config with a direct `node dist/index.js` invocation so your agent picks up your local changes without a publish cycle:\n\n```json\n{\n  \"mcpServers\": {\n    \"missionplanner-dev\": {\n      \"command\": \"node\",\n      \"args\": [\"C:\\\\path\\\\to\\\\missionplanner-mcp-server\\\\dist\\\\index.js\"]\n    }\n  }\n}\n```\n\n### Code layout\n\n```\nsrc/\n├─ index.ts            ← entry point, CLI parsing, transport selection\n├─ server.ts           ← McpServer factory, wires tools + resources\n├─ bridge-client.ts    ← typed HTTP client for the MP bridge\n├─ semver.ts           ← minimal semver parse + range check\n├─ tools/\n│  ├─ mp-status.ts\n│  ├─ list-params.ts\n│  ├─ get-param.ts\n│  └─ search-params.ts\n└─ resources/\n   ├─ params-current.ts\n   └─ param-by-name.ts\n```\n\n### Testing against a mock bridge\n\nThere are no unit tests yet — contributions welcome. The easiest harness is a small Node HTTP server that stubs `/status`, `/params`, and `/params/{name}`. The bridge contract is specified in [`MCP_BRIDGE_DESIGN.md`](https://github.com/ahmetkca/MissionPlanner/blob/feat/mcp-bridge/docs/MCP_BRIDGE_DESIGN.md) §3.\n\n---\n\n## Architecture and contribution guide\n\nThe full design — including the HTTP contract, threading model, metadata sourcing, versioning handshake, and ADRs — lives in the Mission Planner fork:\n\n- **HTTP bridge contract:** [`MCP_BRIDGE_DESIGN.md`](https://github.com/ahmetkca/MissionPlanner/blob/feat/mcp-bridge/docs/MCP_BRIDGE_DESIGN.md)\n- **Project-wide architecture + vision:** [`ARCHITECTURE.md`](https://github.com/ahmetkca/MissionPlanner/blob/feat/mcp-bridge/docs/ARCHITECTURE.md)\n- **ADRs:** [`docs/adrs/`](https://github.com/ahmetkca/MissionPlanner/tree/feat/mcp-bridge/docs/adrs)\n\nPlease read the design doc before proposing changes that touch the HTTP contract or the MCP tool surface. Bumping `bridge_api_version` is not free — both sides have to agree.\n\n---\n\n## Roadmap\n\nThe long-term vision is to expose **full Mission Planner context** to AI agents, not just parameters. Near-term targets:\n\n- **Parameter writes** (`PARAM_SET` → `POST /params/{name}`). Designed for in the bridge contract; not enabled.\n- **Missions / waypoints.** Read first, then write.\n- **Live telemetry snapshot** — attitude, battery, GPS fix, flight mode, armed state.\n- **Logs / dataflash** listing and retrieval.\n\nEach of these is a contract-extending change — new endpoints in the bridge, new MCP tools here. Proposals welcome.\n\n---\n\n## License\n\nMIT © Ahmet Karapinar\n","readmeFilename":"README.md"}