<p align="center">
  <img src="https://github.com/stfade/moth/blob/main/assets/moth-logo.png?raw=true" width="120" alt="Moth Logo" />
</p>

<h1 align="center">Moth</h1>

<p align="center">
  <a href="https://www.npmjs.com/package/@stfade/moth"><img src="https://badge.fury.io/js/@stfade%2Fmoth.svg" alt="npm version"></a>
  <a href="https://opensource.org/licenses/MIT"><img src="https://img.shields.io/badge/License-MIT-yellow.svg" alt="License: MIT"></a>
</p>

Moth is a lightweight MCP server for project-local bug-fix analysis and verified fix memory.

## What Moth Does

Moth receives error output through MCP, redacts likely secrets, normalizes the failure, detects the likely stack, checks project-local fix memory, and returns a structured fix brief.

Moth does not edit code, run shell commands, crawl repositories, require a backend, or maintain a global bug database.

## Why Moth?

Bug-fix context is often local to a project: the command that failed, the framework in use, nearby configuration, and fixes that have already worked or failed in that repo.

Moth keeps that workflow small and explicit. It analyzes provided error context, suggests a best first fix, and records only verified fix outcomes in project-local memory.

## Quick Start

Requires Node.js 18+.

Run directly:

```bash
npx -y @stfade/moth moth-mcp
```

Or install globally:

```bash
npm install -g @stfade/moth
moth-mcp
```

## Generic MCP config

```json
{
  "mcpServers": {
    "moth": {
      "command": "npx",
      "args": ["-y", "@stfade/moth", "moth-mcp"]
    }
  }
}
```

## Usage Example

When using Moth with a supported AI agent, you can include a simple prompt like this along with your error:

> "Use Moth to analyze this error before fixing it."

## Supported Clients

| Client | Status | Setup |
| --- | --- | --- |
| Codex | Local plugin-ready | [Setup](integrations/codex/README.md) |
| Claude Code | Local plugin-ready | [Setup](integrations/claude-code/README.md) |
| Cursor | Plugin scaffold | [Setup](integrations/cursor/README.md) |
| Gemini CLI | Extension scaffold | [Setup](integrations/gemini-cli/README.md) |
| Gemini Antigravity | MCP config-ready | [Setup](integrations/gemini-antigravity/README.md) |
| OpenCode | MCP config-ready | [Setup](integrations/opencode/README.md) |
| Generic MCP | Config-ready | [Setup](integrations/generic/README.md) |

“Local plugin-ready” means the integration wrapper is included and can be tested locally. Marketplace submission and approval are not included yet.

## Tools

Moth exposes exactly two MCP tools.

### `analyze_error`

Analyzes provided error output before a fix is attempted.

Input fields:

- `error_output`
- `command?`
- `cwd?`
- `package_context?`
- `relevant_files?`
- `environment?`

Output fields:

- `analysis_id`
- `fingerprint`
- `stack`
- `likely_cause`
- `best_first_fix`
- `verification`
- `prior_project_fixes`
- `avoid`
- `confidence`

### `remember_fix_result`

Records verified project-local fix memory.

Input fields:

- `analysis_id`
- `fingerprint`
- `stack`
- `fix_attempted`
- `verification_command`
- `verification_result: "passed" | "failed"`
- `notes?`

The public `worked` input is rejected. `worked` is derived from `verification_result`.

## Verified Memory Lifecycle

```txt
analyze_error
→ apply/attempt fix
→ run verification command
→ remember_fix_result
```

Call `remember_fix_result` only when:

1. a fix/change was actually attempted
2. the verification command actually ran
3. the result is clearly `passed` or `failed`

Do not call it for suggestions, skipped changes, missing verification, ambiguous results, or guesses.

## Local Memory

Verified project-local fix memory is stored at:

```txt
.moth/fix-memory.jsonl
```

Moth keeps a small Moth-owned analysis registry outside the project so `remember_fix_result` can map `analysis_id` back to the correct project path after an MCP server restart.

## Skills

Moth includes concise skills for compatible agents:

- `moth-debug-first-fix`
- `moth-source-backed-research`
- `moth-verify-fix`

The MCP server itself does not perform live web research. Compatible agents may use their own search tools, guided by Moth skills, when external sources are needed.

## Safety

- read-only by default
- no source edits
- no shell execution
- no repo-wide scan
- no background watcher
- no external service required
- redacts likely secrets before analysis, responses, and memory writes

## Development

```bash
pnpm install
pnpm test
pnpm build
pnpm dev
npm pack --dry-run
```

## License

MIT