npm package: @hosho/mcp-server
Description: Hosho MCP server — AI prompt diagnosis and optimization
Latest version: 0.1.10

# Hosho

Hosho is an MCP server that connects to your coding agent and helps you diagnose, audit, and fix AI agent prompt issues. It classifies problems, identifies the responsible prompts, audits them line-by-line, and rewrites with targeted fixes — all from within your IDE.

## Quick Start

```bash
claude mcp add hosho -e HOSHO_API_KEY=your-key -- npx -y @hosho/mcp-server@latest
```

Then tell your agent:

> "diagnose: my agent's images look generic and low quality"

Hosho takes it from there.

## What You Need

### API Key

You'll receive a Hosho API key (`pdx_...`) from the Hosho team. This authenticates your requests.

### Required Documents

Hosho relies on three documents to understand your project. Here's what each does and where it lives:

| Document | What it does | Location | Created by |
|----------|-------------|----------|------------|
| **Project Config** | Tells Hosho where your prompt files and architecture doc live | `.hosho/config.yaml` in your repo root | Interactive — run `hosho__setup` and your coding agent guides you through it |
| **Client MCP Config** | Tells your coding agent how to launch the Hosho MCP server | Varies by IDE (see [Setup by IDE](#setup-by-ide) below) | You |
| **Architecture Doc** | Describes how your agents connect — models, data flow, prompt chains | Anywhere in your repo (referenced from Project Config) | You (optional but recommended — significantly improves attribution accuracy) |

**Project Config** example (`.hosho/config.yaml`):

```yaml
# Recommended: glob patterns auto-discover prompts across your repo
prompt_patterns:
  - "**/*system-prompt*.md"
  - "**/*user-prompt*.md"

# Alternative: explicit directories (also supported)
# prompt_dirs:
#   - ./prompts
#   - ./agents/content-agent

architecture_doc: docs/agent-architecture.md
```

Glob patterns are recommended — they catch new prompts automatically when you add agents, without config changes. You can use both `prompt_patterns` and `prompt_dirs` together.

**Architecture Doc** — If you have a document describing your agent pipeline (which agents exist, what data flows between them, which models they use), point Hosho to it. Without it, Hosho infers relationships from prompt text alone. With it, attribution accuracy improves significantly.

If you don't have one, run `/arch-doc` in Claude Code — it scans your codebase and generates the document automatically, then registers it in `.hosho/config.yaml`. You can also re-run it after adding or removing agents to keep the document current.

## How It Works

Here's what a typical session looks like:

> **You:** "hey, help me figure out why the images I'm generating are not looking good"
>
> **Hosho diagnoses** the issue and classifies the root cause as **prompt** (vs context, model, or agent coordination)
>
> **Hosho attributes** the problem to specific prompts — `image-generator-system.md` (asset descriptions lack visual detail) and `content-planner.md` (style requirements underspecified)
>
> **Hosho audits** `image-generator-system.md` line-by-line — "Line 87: image prompt template uses generic descriptors. Add style, mood, and composition constraints."
>
> **Hosho rewrites** the prompt and shows a diff with targeted improvements
>
> **You:** "looks good, apply it"

The tools chain naturally: **diagnose** the issue, **attribute** it to specific prompts, **audit** the top prompt line-by-line, then **rewrite** with a diff view.

## Setup by IDE

| IDE | Config file | Scope |
|-----|------------|-------|
| **Claude Code** | `claude mcp add hosho -e HOSHO_API_KEY=your-key -- npx -y @hosho/mcp-server@latest` | — |
| **Cursor** | `.cursor/mcp.json` | Project |
| **Conductor** | `.mcp.json` | Project |
| **VS Code** | `.vscode/mcp.json` | Project |
| **Windsurf** | `~/.codeium/windsurf/mcp_config.json` | Global |
| **Claude Desktop** | `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) | Global |

For **Cursor, Conductor, Windsurf, and Claude Desktop**, add this block:

```json
{
  "mcpServers": {
    "hosho": {
      "command": "npx",
      "args": ["-y", "@hosho/mcp-server@latest"],
      "env": {
        "HOSHO_API_KEY": "your-key"
      }
    }
  }
}
```

For **VS Code** (GitHub Copilot), the root key is `servers` instead of `mcpServers`:

```json
{
  "servers": {
    "hosho": {
      "command": "npx",
      "args": ["-y", "@hosho/mcp-server@latest"],
      "env": {
        "HOSHO_API_KEY": "your-key"
      }
    }
  }
}
```

## Reference

### Available Tools

| Tool | What it does |
|------|-------------|
| `hosho__diagnose` | Classify an issue as prompt, context, model, or agent coordination |
| `hosho__attribute` | Identify which prompts are most responsible for the issue |
| `hosho__line_audit` | Get line-level fix suggestions for a specific prompt |
| `hosho__rewrite` | Generate an improved version of the prompt with a diff view |
| `hosho__test` | Run a prompt against an LLM and see the output |
| `hosho__setup` | Configure Hosho for your project (additive — safe to re-run) |
| `hosho__investigate` | Full diagnostic workflow — chains diagnose → attribute → audit → rewrite in a single call |
| `hosho__arch_doc` | Scan the codebase and generate (or update) an architecture document for Hosho |

### Error Messages

| Message | Cause | Fix |
|---------|-------|-----|
| `API error: ...` | Hosho API call failed (timeout, HTTP error, network) | Check your API key and network. The message includes the endpoint path. |
| `Prompt "X" not found` | Prompt slug doesn't match any file in configured directories | Check `prompt_dirs` / `prompt_patterns` in `.hosho/config.yaml` |
| `Architecture doc at X not found` | `architecture_doc` is configured but the file doesn't exist | Update the path in `.hosho/config.yaml` or run `/arch-doc` to regenerate |
| `No prompts found in configured directories` | No prompt files discovered | Run `hosho__setup` to configure prompt directories or patterns |
| `Configuration error: ...` | Missing or invalid `.hosho/config.yaml` | Run `hosho__setup` or set `HOSHO_API_KEY` env var |

### Debugging

Inspect the server with [MCP Inspector](https://github.com/modelcontextprotocol/inspector):

```bash
HOSHO_API_KEY=your-key npx @modelcontextprotocol/inspector npx -y @hosho/mcp-server@latest
```

### Requirements

- Node.js 18+
- A Hosho API key