# Reported issues for airmcp

Pod holds 14 of 14 problems reported by people outside the maintainer team. Issues filed by the project's own owners, members and collaborators are excluded entirely — a maintainer's release checklist is not a warning to a prospective user.

Back to [airmcp](/mcp/airmcp).

## Most discussed

### bug: "custom" profile unrecognized at runtime — falls back to "starter", ignoring disabledModules

## Description

When a user selects a custom set of modules via `npx airmcp init` (one that doesn't match any predefined profile), `config.json` is saved with `"profile": "custom"` and a `disabledModules` list. At runtime, however, `"custom"` is not recognized as a valid profile name, causing `normalizeProfileName("custom")` to return `null`. The fallback logic in `parseConfig()` then sets `activeProfile = "starter"`, which overrides the `disabledModules` from the config file and only enables th

[Read the thread](https://github.com/heznpc/AirMCP/issues/358) · 2026-06-30 · closed · external user · 2 comments

### list_notes, search_notes, list_reminders, search_reminders fail with output validation error; update_note approval prompt never surfaces

Environment

AirMCP: latest via npx airmcp
macOS: 26.3.1
Node.js: 25.8.2
MCP Client: Claude Desktop (Cowork mode)
npx airmcp doctor: 19 passed, 2 warnings (Swift bridge not built, npm registry check)

Bug 1: Output validation errors on list/search tools
list_notes, search_notes, list_reminders, and search_reminders all fail with:
MCP error -32602: Output validation error: Tool [tool_name] has an output schema but no structured content was provided
These tools declare an output schema, but the se

[Read the thread](https://github.com/heznpc/AirMCP/issues/28) · 2026-03-28 · closed · external user · 2 comments

### docs: refresh CONTRIBUTING.md against the current registration and drift workflow

## Problem

`CONTRIBUTING.md` describes an older development contract in several places:

- it tells contributors to register tools with `server.tool()`, while current modules use `server.registerTool()`
- it hard-codes an old aggregate catalog count in the review section
- its new-tool steps point contributors at manual count and landing-page updates. `README.md` and the `docs/site/**` pages listed in `scripts/count-stats.mjs` are now owned by generated drift guards, so those manual steps shoul

[Read the thread](https://github.com/heznpc/AirMCP/issues/401) · 2026-07-29 · closed · 1 comment

### docs: keep contribution templates in sync with MODULE_MANIFEST

## Problem

The public bug/feature forms and PR checklist have drifted from `src/shared/modules.ts`.

Examples:

- the issue forms omit `speech`, `health`, `memory`, `audit`, `spatial_prep`, `webhooks`, and `powerautomate`
- the PR checklist omits several current modules and still contains the older `Semantic` label

A contributor reporting or changing a current module cannot select the right area.

## Scope

- Update both issue-form module dropdowns and the PR template so every entry in `MODULE

[Read the thread](https://github.com/heznpc/AirMCP/issues/400) · 2026-07-29 · closed · 1 comment

### Add `get_wifi_status` tool to system module

## What

Add a \`get_wifi_status\` tool to the system module that returns Wi-Fi network name, signal strength, and connection state.

## How

1. Add a script to \`src/system/scripts.ts\`:
   \`\`\`javascript
   // Use networksetup or system_profiler via doShellScript
   app.doShellScript('networksetup -getairportnetwork en0')
   \`\`\`
2. Register tool in \`src/system/tools.ts\` with \`readOnlyHint: true\`
3. Add test in \`tests/system-scripts.test.js\`

## Acceptance Criteria

- [ ] Returns \`{

[Read the thread](https://github.com/heznpc/AirMCP/issues/6) · 2026-03-15 · closed · 1 comment

### Document all environment variables in README

## What

Add an \"Environment Variables\" section to the README listing all \`AIRMCP_*\` and \`GEMINI_API_KEY\` variables with descriptions and defaults.

## Why

The variables are defined in \`src/shared/constants.ts\` and \`src/shared/config.ts\` but there's no user-facing reference. Users have to read source code to discover configuration options.

## How

1. Grep \`src/shared/constants.ts\` and \`src/shared/config.ts\` for all \`process.env\` references
2. Create a table in README with: Vari

[Read the thread](https://github.com/heznpc/AirMCP/issues/5) · 2026-03-15 · closed · 1 comment

### Improve error messages when macOS permissions are missing

## What

When a tool fails because of missing macOS permissions (Automation, Full Disk Access, etc.), the error message should clearly tell the user which permission is needed and how to grant it.

## Current Behavior

JXA throws generic errors like \`osascript error: Application isn't running\` or \`-1743\` (permission denied).

## Expected Behavior

Catch common JXA error codes and return actionable messages:
- \`-1743\`: \"Permission denied. Grant Automation access: System Settings > Privacy 

[Read the thread](https://github.com/heznpc/AirMCP/issues/4) · 2026-03-15 · closed · 1 comment

### Add `get_battery_status` tool to system module

## What

Add a `get_battery_status` tool to `src/system/tools.ts` that returns battery level, charging state, and power source.

## Why

Users frequently want AI to check battery before starting long operations. This is one of the most requested system info tools.

## How

1. Add a JXA script to `src/system/scripts.ts`:
   ```javascript
   const app = Application.currentApplication();
   app.includeStandardAdditions = true;
   const raw = app.doShellScript('pmset -g batt');
   // Parse battery p

[Read the thread](https://github.com/heznpc/AirMCP/issues/1) · 2026-03-15 · closed · 1 comment

## Most recent

### bug(finder): `recent_files` always returns 0 results — `$time` is shell-expanded inside the mdfind query

## Summary

`recent_files` returns `{"total": 0, "files": []}` for every input, including an explicit absolute `folder`. The mdfind query is malformed before it reaches `mdfind`.

This is separate from the `folder` default problem (filed separately); fixing that one alone does not fix this.

## Environment

- airmcp 2.16.5 (installed via `npm install -g airmcp`)
- macOS 26.5 (Darwin 25.5.0), Apple Silicon

## Reproduction

| arguments | result |
|---|---|
| `{"days": 2, "limit": 3}` | `total: 0`

[Read the thread](https://github.com/heznpc/AirMCP/issues/460) · 2026-08-21 · open · external user · 0 comments

### test(finder): add script ↔ outputSchema shape contract (*_EXAMPLE) for finder JXA scripts

## Problem

`tests/script-shape-contract.test.js` guards against a silent drift class: `scripts.ts` changing the JSON it emits without the matching `outputSchema` update (or vice versa). Runtime tests mock `runJxa`, so the mock return value becomes `structuredContent` verbatim — they cannot catch this drift.

That contract currently exists only for **messages, shortcuts, and health**. The `finder` module has outputSchema-bearing tools (list_directory, search_files, recent_files, get_file_info) w

[Read the thread](https://github.com/heznpc/AirMCP/issues/411) · 2026-07-29 · closed · 0 comments

### test(reminders): add script ↔ outputSchema shape contract (*_EXAMPLE) for reminders JXA scripts

## Problem

`tests/script-shape-contract.test.js` guards against a silent drift class: `scripts.ts` changing the JSON it emits without the matching `outputSchema` update (or vice versa). Runtime tests mock `runJxa`, so the mock return value becomes `structuredContent` verbatim — they cannot catch this drift.

That contract currently exists only for **messages, shortcuts, and health**. The `reminders` module has outputSchema-bearing tools (list_reminders, search_reminders, read_reminder, list_rem

[Read the thread](https://github.com/heznpc/AirMCP/issues/409) · 2026-07-29 · closed · 0 comments

### test(calendar): add script ↔ outputSchema shape contract (*_EXAMPLE) for calendar JXA scripts

## Problem

`tests/script-shape-contract.test.js` guards against a silent drift class: `scripts.ts` changing the JSON it emits without the matching `outputSchema` update (or vice versa). Runtime tests mock `runJxa`, so the mock return value becomes `structuredContent` verbatim — they cannot catch this drift.

That contract currently exists only for **messages, shortcuts, and health**. The `calendar` module has outputSchema-bearing tools (list_events, read_event, search_events, get_upcoming_event

[Read the thread](https://github.com/heznpc/AirMCP/issues/407) · 2026-07-29 · closed · 0 comments

### docs: repair stale testing-guide paths and dependency guidance

## Problem

The documentation-site testing guide has stale examples that no longer match the repository:

- it lists `tests/scripts.test.js`, which does not exist
- several example filenames no longer describe the current suite layout
- the TypeScript OOM section says AirMCP pins Zod 3.24, while the project now uses Zod 4
- some Jest command examples should be checked against the installed Jest CLI

The root testing guide and the site guide consequently give contributors different instructions.

[Read the thread](https://github.com/heznpc/AirMCP/issues/402) · 2026-07-29 · closed · 0 comments

### Calendar tools can return empty results after permission grant because EventKit store is not refreshed

### AirMCP Version

2.11.0

### Module

calendar

### What happened?

**Summary**

First is first: **I am not a programmer or use github.** I asked Hermes to fix the issue a generate a report. So this is it. If you find it useful I can report another bug it detected.

On macOS, AirMCP calendar access can appear to succeed, but list_calendars returns an empty list ([]) even though the user has multiple calendars, including normal local and remote/subscribed calendars.

This appears to be a Swift/

[Read the thread](https://github.com/heznpc/AirMCP/issues/145) · 2026-04-24 · closed · external user · 0 comments

The remaining reports are on [the project's issue tracker](https://github.com/heznpc/AirMCP/issues).