npm package: @msegoviadev/api-mind
Description: LLM tools for API discovery from .mind spec files
Author: msegoviadev
Latest version: 0.4.0

# api-mind

LLM tools for API discovery from .mind spec files. Works with `.mind` files generated by [spec-mind](https://github.com/msegoviadev/spec-mind).

## Why

LLMs interacting with HTTP APIs need to discover endpoints, understand contracts, and make requests. api-mind provides 3 tools for discovery and context:

- **list_apis** - Discover available APIs
- **list_endpoints** - Find endpoints across APIs
- **get_endpoint_schema** - Get base URL, auth requirements, and schema

The LLM then constructs and executes curl commands via the `bash` tool with full transparency.

## Installation

### Quick Install

```bash
# Project-level (recommended)
curl -sSL https://raw.githubusercontent.com/msegoviadev/api-mind/main/install.sh | bash

# Global (user-wide, available for all projects)
curl -sSL https://raw.githubusercontent.com/msegoviadev/api-mind/main/install.sh | bash -s -- --global
```

The script will:
1. Add `@msegoviadev/api-mind` to your `opencode.json`
2. Download `API-MIND.md` to the appropriate location
3. Add `@API-MIND.md` reference to your `AGENTS.md`

### Manual Installation

<details>
<summary>Click to expand manual installation steps</summary>

#### 1. Add plugin to your OpenCode config

Add `@msegoviadev/api-mind` to your `opencode.json` or `opencode.jsonc`:

```json
{
  "plugin": ["@msegoviadev/api-mind"]
}
```

OpenCode will automatically install the plugin from npm on startup.

#### 2. Download the context file

Run this command in your project root:

```bash
curl -sSL https://raw.githubusercontent.com/msegoviadev/api-mind/main/API-MIND.md -o API-MIND.md
```

#### 3. Reference in your AGENTS.md

Add this line to your `AGENTS.md`:

```markdown
@API-MIND.md
```

</details>

## Setup

1. Place OpenAPI specs in `specs/` folder:
   ```
   specs/
     api1.yaml
     api2.yaml
   ```

2. Generate `.mind` files using spec-mind:
   ```bash
   spec-mind sync --no-notation ./specs/
   ```

3. Commit `.mind` files alongside source specs:
   ```
   specs/
     api1.yaml
     api1.mind   # generated
     api2.yaml
     api2.mind   # generated
   ```

4. Tools automatically load from `specs/*.mind`

## Configuration

By default, api-mind looks for `.mind` files in the `specs/` directory.

To customize the specs location, create an `api-mind.json` file in your project root:

```json
{
  "specsDir": "documentation/api-specs"
}
```

The path is relative to your project root (where you run `opencode`).

## Tools

### list_apis

Lists all APIs loaded from the specs folder.

```
Input: none
Output: JSON with API names, titles, base URLs, and environments
```

Call first to discover what APIs are available.

### list_endpoints

Lists endpoints across all APIs.

```
Input:
  filter (optional): Substring match on method, path, or section

Output: JSON with environments and endpoint list
```

Call to find specific endpoints.

### get_endpoint_schema

Returns full context for an endpoint.

```
Input:
  api: API name
  method: HTTP method
  path: Endpoint path

Output: Text block with base URL, environments, auth, and schema
```

Call before constructing curl to understand the endpoint.

## Workflow

```
list_apis → list_endpoints → get_endpoint_schema → [LLM constructs curl] → bash
```

1. `list_apis` - Discover available APIs
2. `list_endpoints` - Find relevant endpoints
3. `get_endpoint_schema` - Get context (URL, auth, schema)
4. LLM constructs curl command with proper URL and headers
5. LLM executes via `bash` tool

## Auth Patterns

When `get_endpoint_schema` shows auth requirements, construct headers:

| Auth in Schema | curl Header |
|----------------|-------------|
| `None` | No header |
| `bearer` | `-H 'Authorization: Bearer <TOKEN>'` |
| `oauth2 <scopes>` | `-H 'Authorization: Bearer <TOKEN>'` |
| `api_key <header>` | `-H '<header>: <KEY>'` |
| `basic` | `-H 'Authorization: Basic <base64>'` |

## Related

- [spec-mind](https://github.com/msegoviadev/spec-mind) - Generate `.mind` files from OpenAPI specs

## Development

### Build

```bash
bun run build
```

### Test Locally

For local testing without publishing, create a symlink in your test project:

```bash
# In your test project
mkdir -p .opencode/plugins
ln -s /path/to/api-mind/src/index.ts .opencode/plugins/api-mind.ts
ln -s /path/to/api-mind/API-MIND.md API-MIND.md
```

## License

MIT