open-index/open-npm huggingface dataset:
npm package: @pulsemcp/air-adapter-claude
Description: AIR adapter for Claude Code — translates AIR config to Claude Code format
Latest version: 0.0.19

# @pulsemcp/air-adapter-claude

AIR adapter extension for [Claude Code](https://claude.ai/code). Translates AIR artifacts into Claude Code's native format and prepares working directories for agent sessions.

## Installation

```bash
npm install @pulsemcp/air-adapter-claude
```

## Usage

### With the AIR CLI

```bash
# Install the adapter globally alongside the CLI
npm install -g @pulsemcp/air-cli @pulsemcp/air-adapter-claude

# Start a Claude Code session
air start claude --root web-app
```

### Programmatic

```typescript
import { resolveArtifacts } from "@pulsemcp/air-core";
import { ClaudeAdapter } from "@pulsemcp/air-adapter-claude";

const artifacts = await resolveArtifacts("./air.json");
const adapter = new ClaudeAdapter();

// Prepare a working directory for a Claude Code session
const session = await adapter.prepareSession(artifacts, "./my-project", {
  root: artifacts.roots["web-app"],
});

// session.configFiles  — paths written (.mcp.json, etc.)
// session.skillPaths   — skill dirs created in .claude/skills/
// session.startCommand — { command: "claude", args: [...], cwd: "..." }
```

## What `prepareSession()` does

1. **Writes `.mcp.json`** — translates AIR MCP server configs to Claude Code format (secret resolution is handled by transform extensions, not the adapter)
2. **Injects skills** — copies SKILL.md files and associated content into `.claude/skills/{name}/`
3. **Copies references** — attaches referenced documents into `.claude/skills/{name}/references/`
4. **Respects local priority** — if a skill directory already exists in the target, it is not overwritten

## Translation Details

| AIR Format | Claude Code Format |
|------------|-------------------|
| `mcp.json` (flat map with `type`, `title`, `description`) | `.mcp.json` (`mcpServers` wrapper, strips metadata) |
| `stdio` servers | `{ command, args, env }` |
| `sse`/`streamable-http` servers | `{ url, headers, oauth }` |
| OAuth `redirectUri` | Extracted as `callbackPort` |
| Plugin `id` | `name` |
| Plugin `skills`/`mcp_servers`/`hooks` | Stripped (used by CLI for deduplication) |
npm package: @pulsemcp/air-cli
Description: CLI for the AIR (Agent Infrastructure Repository) framework
Latest version: 0.0.19

# @pulsemcp/air-cli

CLI for the [AIR](https://github.com/pulsemcp/air) framework. Validates configs, lists artifacts, initializes new setups, and starts agent sessions.

## Installation

```bash
npm install -g @pulsemcp/air-cli
```

## Commands

```bash
# Initialize a new AIR configuration at ~/.air/
air init

# Validate a JSON file against its AIR schema
air validate ~/.air/air.json
air validate ~/.air/mcp/mcp.json

# List available artifacts
air list skills
air list mcp
air list roots

# Start an agent session
air start claude
air start claude --root web-app
air start claude --root web-app --dry-run
```

## Agent Adapters

`air start <agent>` discovers adapters dynamically. Install the adapter package for your agent:

```bash
# Claude Code (officially maintained)
npm install -g @pulsemcp/air-adapter-claude
```

The CLI looks for `@pulsemcp/air-adapter-<agent>` packages. If the package is installed, the agent is available.

## Environment Variables

| Variable | Description |
|----------|-------------|
| `AIR_CONFIG` | Override the path to `air.json` (default: `~/.air/air.json`) |
npm package: @pulsemcp/air-core
Description: AIR core — config resolution, validation, schemas, and extension interfaces
Latest version: 0.0.19

# @pulsemcp/air-core

Core package for the [AIR](https://github.com/pulsemcp/air) framework. Provides config resolution, validation, JSON schemas, and extension interfaces.

## Installation

```bash
npm install @pulsemcp/air-core
```

## Usage

```typescript
import {
  resolveArtifacts,
  validateJson,
  mergeArtifacts,
  emptyArtifacts,
} from "@pulsemcp/air-core";

// Resolve all artifacts from an air.json file
const artifacts = await resolveArtifacts("~/.air/air.json");

// Validate a JSON file against its AIR schema
const result = validateJson(data, "skills");

// Merge two artifact sets (later wins for matching IDs)
const merged = mergeArtifacts(base, override);
```

### With a Catalog Provider (remote URIs)

```typescript
import { resolveArtifacts } from "@pulsemcp/air-core";
import { GitHubCatalogProvider } from "@pulsemcp/air-provider-github";

const artifacts = await resolveArtifacts("./air.json", {
  providers: [new GitHubCatalogProvider()],
});
```

## What's in this package

- **Config resolution** — `resolveArtifacts()`, `loadAirConfig()`, `mergeArtifacts()`, `emptyArtifacts()`
- **Validation** — `validateJson()` using AJV against AIR JSON Schemas
- **Schema utilities** — `loadSchema()`, `detectSchemaType()`, `detectSchemaFromValue()`
- **All artifact types** — `SkillEntry`, `McpServerEntry`, `RootEntry`, `ReferenceEntry`, `PluginEntry`, `HookEntry`
- **Extension interfaces** — `AgentAdapter`, `CatalogProvider`, `PrepareTransform`, `AirExtension`
- **Session types** — `AgentSessionConfig`, `StartCommand`, `PrepareSessionOptions`, `PreparedSession`

## Extension Interfaces

Core defines four extension points that other packages implement:

| Interface | Purpose | Example |
|-----------|---------|---------|
| `AgentAdapter` | Translate AIR config for a specific agent | `@pulsemcp/air-adapter-claude` |
| `CatalogProvider` | Resolve remote URIs in air.json | `@pulsemcp/air-provider-github` |
| `PrepareTransform` | Post-prepare transforms on `.mcp.json` | `@pulsemcp/air-secrets-env`, `@pulsemcp/air-secrets-file` |
| `AirExtension` | Extension metadata for CLI discovery | All extension packages |
npm package: @pulsemcp/air-provider-github
Description: AIR catalog provider for GitHub — resolves github:// URIs to artifact indexes
Latest version: 0.0.19

# @pulsemcp/air-provider-github

AIR catalog provider for GitHub. Resolves `github://` URIs in `air.json` by fetching file content from the GitHub REST API.

## Installation

```bash
npm install @pulsemcp/air-provider-github
```

## Usage

### In air.json

Reference remote artifact indexes using `github://` URIs:

```json
{
  "name": "my-team",
  "skills": [
    "github://acme/air-org/skills/skills.json",
    "./skills/skills.json"
  ],
  "mcp": [
    "github://acme/air-org/mcp/mcp.json",
    "./mcp/mcp.json"
  ]
}
```

### Programmatic

```typescript
import { resolveArtifacts } from "@pulsemcp/air-core";
import { GitHubCatalogProvider } from "@pulsemcp/air-provider-github";

const provider = new GitHubCatalogProvider();
// Or with a token for private repos:
// const provider = new GitHubCatalogProvider({ token: "ghp_..." });

const artifacts = await resolveArtifacts("./air.json", {
  providers: [provider],
});
```

## URI Format

```
github://owner/repo/path/to/file.json
github://owner/repo@ref/path/to/file.json
```

| Component | Description |
|-----------|-------------|
| `owner` | GitHub organization or user |
| `repo` | Repository name |
| `@ref` | Optional git ref (branch, tag, commit SHA) — appended to the repo name |
| `path` | Path to the JSON file within the repo |

Examples:
- `github://acme/air-org/skills/skills.json` — latest from default branch
- `github://acme/air-org@v1.0.0/mcp/mcp.json` — pinned to a tag
- `github://acme/air-org@main/mcp/mcp.json` — explicit branch
- `github://acme/air-org@abc123/mcp/mcp.json` — pinned to a commit SHA
- `github://acme/air-org/mcp/mcp.json@feature/branch` — ref with slashes (use legacy syntax)

The legacy syntax `github://owner/repo/path@ref` (ref at end of path) is also supported for backward compatibility.

> **Note:** Refs containing slashes (e.g., `feature/branch`) cannot be expressed with the repo-level `@ref` syntax because the URI is split on `/`. Use the legacy path-level syntax for such refs.

## Authentication

| Scenario | Auth Required? | How |
|----------|---------------|-----|
| Public repository | No | Works out of the box |
| Private repository | Yes | Set `AIR_GITHUB_TOKEN` env var or pass `token` option |
| Higher rate limits | Optional | Authenticated requests get 5,000 req/hr vs 60 |

```bash
export AIR_GITHUB_TOKEN=ghp_your_token_here
```

## Caching

Fetched files are cached locally at `~/.air/cache/github/{owner}/{repo}/{ref}/{path}`. Delete the cache directory to force a re-fetch.