open-index/open-npm huggingface dataset:
npm package: @mcpher/fiddler
Description: A port of Apps Script library bmfiddler to Node - Google Sheets
Latest version: 1.0.2

# Fiddler
Node port of Apps Script bmFiddler library

## More info 
See [fiddler](https://ramblings.mcpher.com/gassnippets2/afunctionalapproachtofiddlingwithsheetdata/) for more information and search mcpher.com for fiddler - there are lots of articles about things you can do with fiddler.

## gas-fakes
This uses built in Apps Script Services, so for running in Node, we need to simulate them with gas-fakes - see [gas-fakes](https://ramblings.mcpher.com/a-proof-of-concept-implementation-of-apps-script-environment-on-node/) for more information and related articles. 


## Getting started

Fiddler can be used without apps script services, but whenever you access sheets you'll also need gas-fakes on Node which emulates Apps Script built in services. See [gas-fakes](https://ramblings.mcpher.com/a-proof-of-concept-implementation-of-apps-script-environment-on-node/) for more information and related articles and the [gas-fakes](https://github.com/brucemcpherson/gas-fakes) repository for more information.

### To install fiddler

npm i @mcpher/fiddler

### To use with gas fakes

npm i @mcpher/gas-fakes

#### Authentication
You can use gas-fakes-cli for authentication - see [gas-fakes](https://github.com/brucemcpherson/gas-fakes) for more information.
 

## usage

For details on using fiddler, see [fiddler](https://ramblings.mcpher.com/gassnippets2/afunctionalapproachtofiddlingwithsheetdata/) and  [related articles](https://ramblings.mcpher.com/?s=fiddler). These are written for Apps Script, but gas-fakes emulation on Node means it's exactly the same.

````js
  // create a fiddler for a given sheet
  const fiddler = new Fiddler(SpreadsheetApp.openById(myssid).getSheetByName("people"));

  // do things with the data
  fiddler.insertColumn("full name")
  fiddler.mapRows (row=> {
    row["full name"] = row["first name"] + " " + row["last name"]
    return row
  })
  
  // dump the data back to the sheet
  fiddler.dumpValues()

````

You can also use the preFiddler helper to create a fiddler from a sheet name and id. For details see https://ramblings.mcpher.com/vuejs-apps-script-add-ons/helper-for-fiddler/

```js
const fiddler = new PreFiddler().getFiddler({ sheetName: "people", id: myssid, createIfMissing: true })
```
npm package: @mcphero/cli
Description: MCP Hero CLI Adapter
Latest version: 1.3.0

# @mcphero/cli

CLI adapter for [MCPHero](https://github.com/atomicbi/mcphero) — turn your actions into a complete command-line application with help text, option parsing, and styled terminal output via clack.

## Install

```bash
pnpm add @mcphero/core @mcphero/cli
```

## Usage

```typescript
import { mcphero } from '@mcphero/core'
import { cli } from '@mcphero/cli'
import { GreetAction } from './actions/greet.js'

await mcphero({ name: 'mytool', description: 'My CLI Tool', version: '1.0.0' })
  .adapter(cli())
  .action(GreetAction)
  .start()
```

```
$ mytool greet --name "World" --enthusiastic
◇ mytool - greet
ℹ HELLO, WORLD!!!
```

## How Zod Types Map to CLI Options

| Zod Type | CLI Representation |
|----------|-------------------|
| `z.string()` | `--option-name <string>` |
| `z.number()` | `--option-name <number>` |
| `z.boolean()` | `--option-name` / `--no-option-name` |
| `z.enum([...])` | `--option-name <choice>` with choices validation |
| `z.record()` | `--option-name <json>` |
| `.default(value)` | Sets the default in help text |
| `.describe('...')` | Sets the option description |

Field names are automatically converted to `kebab-case`. Action names become subcommands.

## Positional Arguments

Use the `args` property on an action to promote fields to positional arguments:

```typescript
const DeployAction = createAction({
  name: 'deploy',
  input: z.object({
    environment: z.string(),
    dryRun: z.boolean().default(false)
  }),
  args: ['environment'],
  // ...
})
```

```
$ mytool deploy production --dry-run
```

## See Also

- [MCPHero README](https://github.com/atomicbi/mcphero) — Full documentation
- [`@mcphero/core`](https://www.npmjs.com/package/@mcphero/core) — Core library
npm package: @mcphero/core
Description: MCP Hero Core
Latest version: 1.3.0

# @mcphero/core

Core library for [MCPHero](https://github.com/atomicbi/mcphero) — the TypeScript toolkit for building MCP servers and CLI tools from a single set of Actions.

## Install

```bash
pnpm add @mcphero/core
```

## What's Inside

This package provides the foundational building blocks that all MCPHero adapters depend on:

- **`mcphero()`** — Fluent builder to wire up adapters and actions
- **`createAction()`** — Define transport-agnostic actions with Zod input schemas
- **Adapter types** — `Adapter`, `AdapterGenerator`, `AdapterFactory` interfaces for building custom adapters
- **Context** — `MCPHeroContext` key-value store with `fork()` for per-adapter/per-request isolation
- **MCP utilities** — `toolResponse()`, `parseToolResponse()` for MCP response formatting
- **Sideload resources** — `createSideloadResource()` for binary resource handling
- **Zod utilities** — `unwrap()` to recursively unwrap Zod wrapper types

## Usage

```typescript
import { mcphero, createAction } from '@mcphero/core'
import z from 'zod'

const GreetAction = createAction({
  name: 'greet',
  description: 'Greet someone by name',
  input: z.object({
    name: z.string().describe('Name to greet')
  }),
  run: async ({ name }, context) => {
    return { message: `Hello, ${name}!` }
  }
})

// Wire up with any adapter
await mcphero({ name: 'my-app', description: 'My App', version: '1.0.0' })
  .adapter(someAdapter)
  .action(GreetAction)
  .start()
```

## API

### `mcphero(options): MCPHero`

| Option | Type | Description |
|--------|------|-------------|
| `name` | `string` | Server/app name |
| `description` | `string` | Human-readable description |
| `version` | `string` | Semantic version |

Returns a builder with `.adapter()`, `.action()`, `.actions()`, `.set()`, and `.start()`.

### `createAction(action): Action`

| Field | Type | Description |
|-------|------|-------------|
| `name` | `string` | Unique action identifier |
| `description` | `string` | Human-readable description |
| `input` | `z.ZodObject` | Zod schema for input validation |
| `args` | `(keyof I)[]` | Fields to expose as CLI positional arguments |
| `isEnabled` | `(context) => boolean` | Gate action availability per adapter |
| `run` | `(input, context) => Promise<O>` | The action implementation |

### Adapter Interfaces

```typescript
interface Adapter {
  context: MCPHeroContext
  start(actions: Action[]): Promise<void>
  stop(): Promise<void>
}

type AdapterGenerator = (options: MCPHeroOptions, baseContext: MCPHeroContext) => Adapter
type AdapterFactory<T = void> = (options: T) => AdapterGenerator
```

## See Also

- [MCPHero README](https://github.com/atomicbi/mcphero) — Full documentation
- [`@mcphero/mcp`](https://www.npmjs.com/package/@mcphero/mcp) — MCP stdio and HTTP adapters
- [`@mcphero/fastify`](https://www.npmjs.com/package/@mcphero/fastify) — Fastify REST adapter
- [`@mcphero/cli`](https://www.npmjs.com/package/@mcphero/cli) — CLI adapter
- [`@mcphero/vercel`](https://www.npmjs.com/package/@mcphero/vercel) — Vercel serverless adapter
npm package: @mcphero/fastify
Description: MCP Hero Fastify REST Adapter
Latest version: 1.3.0

# @mcphero/fastify

Fastify REST adapter for [MCPHero](https://github.com/atomicbi/mcphero) — expose your actions as a REST API with auto-generated OpenAPI/Swagger documentation.

## Install

```bash
pnpm add @mcphero/core @mcphero/fastify
```

## Usage

```typescript
import { mcphero } from '@mcphero/core'
import { fastify } from '@mcphero/fastify'
import { SearchAction } from './actions/search.js'

await mcphero({ name: 'my-api', description: 'My REST API', version: '1.0.0' })
  .adapter(fastify({ host: 'localhost', port: 8080, logger: true }))
  .action(SearchAction)
  .start()
```

Visit `http://localhost:8080/` for the interactive Scalar API reference.

## Route Mapping

Each action becomes a `POST /{action.name}` route. Zod schemas are converted to JSON Schema for request body validation and OpenAPI documentation.

| Action | Route | Body |
|--------|-------|------|
| `name: 'search'` | `POST /search` | `{ "query": "...", "limit": 10 }` |
| `name: 'greet'` | `POST /greet` | `{ "name": "World" }` |

## Options

`FastifyAdapterOptions` extends Fastify's native `FastifyHttpOptions`, so any Fastify config is supported:

```typescript
fastify({
  host: 'localhost',
  port: 8080,
  logger: {
    level: 'debug',
    transport: { target: 'pino-pretty' }
  },
  connectionTimeout: 30000
})
```

| Option | Type | Default | Description |
|--------|------|---------|-------------|
| `host` | `string` | `undefined` | Bind address |
| `port` | `number` | `undefined` | Listen port |
| *...* | | | Any `FastifyHttpOptions` |

## See Also

- [MCPHero README](https://github.com/atomicbi/mcphero) — Full documentation
- [`@mcphero/core`](https://www.npmjs.com/package/@mcphero/core) — Core library
npm package: @mcphero/logger
Description: MCP Hero Logger
Latest version: 1.3.0

# @mcphero/logger

Logging utilities for [MCPHero](https://github.com/atomicbi/mcphero). Provides a unified `Logger` interface with multiple backends — pino for stream logging, clack for terminal UI, and callback hooks for MCP notifications.

## Install

```bash
pnpm add @mcphero/logger
```

## What's Inside

- **`Logger`** interface — 8 severity levels (`debug` through `emergency`) plus `progress()`
- **`createLogger()`** — Factory that creates a Logger backed by pino, with optional `onLog` and `onProgress` callbacks
- **`createCLILogger()`** — Logger that outputs via `@clack/prompts` for beautiful terminal UI
- **`buildLogLevels()`** — Build a log-level record from a single callback function

## Usage

```typescript
import { createLogger } from '@mcphero/logger'

const logger = createLogger({
  stream: process.stderr,
  onLog: (level, data) => {
    // Hook into log events (e.g., send MCP notifications)
  },
  onProgress: ({ progress, total, message }) => {
    // Hook into progress events
  }
})

logger.info('Starting operation')
logger.progress({ progress: 5, total: 10, message: 'Halfway there' })
```

## Logger Interface

```typescript
interface Logger {
  debug: (data: unknown) => void
  info: (data: unknown) => void
  notice: (data: unknown) => void
  warning: (data: unknown) => void
  error: (data: unknown) => void
  critical: (data: unknown) => void
  alert: (data: unknown) => void
  emergency: (data: unknown) => void
  progress: (options: ProgressOptions) => void
}

interface ProgressOptions {
  progress: number
  total?: number
  message?: string
}
```

## See Also

- [MCPHero README](https://github.com/atomicbi/mcphero) — Full documentation
- [`@mcphero/core`](https://www.npmjs.com/package/@mcphero/core) — Core library
npm package: @mcphero/mcp
Description: MCP Hero MCP Package
Latest version: 1.3.0

# @mcphero/mcp

MCP transport adapters for [MCPHero](https://github.com/atomicbi/mcphero) — expose your actions as MCP tools over stdio, Streamable HTTP, or via a CLI proxy client.

## Install

```bash
pnpm add @mcphero/core @mcphero/mcp
```

## Adapters

### stdio

Standard MCP transport for local tool servers. Communicates over stdin/stdout.

```typescript
import { mcphero } from '@mcphero/core'
import { stdio } from '@mcphero/mcp'

await mcphero({ name: 'my-tools', description: 'My Tools', version: '1.0.0' })
  .adapter(stdio())
  .action(MyAction)
  .start()
```

Configure in Claude Desktop or Claude Code:

```json
{
  "mcpServers": {
    "my-tools": {
      "command": "node",
      "args": ["server.js"]
    }
  }
}
```

### http

Session-based MCP transport over HTTP with SSE streaming and resumability.

```typescript
import { mcphero } from '@mcphero/core'
import { http } from '@mcphero/mcp'

await mcphero({ name: 'my-tools', description: 'My Tools', version: '1.0.0' })
  .adapter(http({ host: 'localhost', port: 8080, allowedHosts: ['localhost'] }))
  .action(MyAction)
  .start()
```

Exposes `POST /mcp` (invoke tools), `GET /mcp` (SSE stream), and `DELETE /mcp` (terminate session). Built on Express with `StreamableHTTPServerTransport` from the MCP SDK.

| Option | Type | Description |
|--------|------|-------------|
| `host` | `string` | Bind address |
| `port` | `number` | Listen port |
| `allowedHosts` | `string[]` | Allowed hosts for DNS rebinding protection |

### cliProxy

MCP CLI proxy client — connects to a running HTTP MCP server and invokes tools from the command line.

```typescript
import { mcphero } from '@mcphero/core'
import { cliProxy } from '@mcphero/mcp'

await mcphero({ name: 'my-tools', description: 'My Tools', version: '1.0.0' })
  .adapter(cliProxy({ url: 'http://localhost:8080/mcp' }))
  .start()
```

## How Actions Become MCP Tools

| Action property | MCP tool property |
|-----------------|-------------------|
| `name: 'searchDocs'` | Tool name: `SearchDocs` (PascalCase) |
| `description` | Tool description |
| `input` (Zod schema) | `inputSchema` (JSON Schema) |
| Return value | `TextContent` JSON response |
| Thrown errors | Structured error response |

Logging notifications (`logger.info()`, `logger.progress()`) are sent to the MCP client as `notifications/message` and `notifications/progress`.

## See Also

- [MCPHero README](https://github.com/atomicbi/mcphero) — Full documentation
- [`@mcphero/core`](https://www.npmjs.com/package/@mcphero/core) — Core library
- [`@mcphero/vercel`](https://www.npmjs.com/package/@mcphero/vercel) — Stateless MCP for Vercel
npm package: @mcphub/gateway
Description: MCPHub Gateway for Claude Desktop
Latest version: 1.0.1

# MCPHub Gateway

A gateway service that connects Claude Desktop to MCPHub servers, enabling access to a wide range of MCP (Model Context Protocol) servers.

## Installation

Install the gateway globally using npm:

```bash
npm install -g @mcphub/gateway
```

## Configuration

### 1. Find the Gateway Path

After installation, find where npm installed the gateway using these commands:

```bash
# This shows the root directory of global packages
npm root -g

# The gateway will be located at:
<npm_global_root>/@mcphub/gateway/dist/src/mcphub-gateway.js
```

Common global package locations:
- macOS (Homebrew Node): `/opt/homebrew/lib/node_modules/@mcphub/gateway/dist/src/mcphub-gateway.js`
- macOS (default): `/usr/local/lib/node_modules/@mcphub/gateway/dist/src/mcphub-gateway.js`
- Windows: `%AppData%\npm\node_modules\@mcphub\gateway\dist\src\mcphub-gateway.js`

Verify the installation and path:
```bash
npm list -g @mcphub/gateway
```

### 2. Configure Claude Desktop

Create or update your Claude Desktop configuration file:

#### On macOS
Location: `~/Library/Application Support/Claude Desktop/config.json`

#### On Windows
Location: `%APPDATA%\Claude Desktop\config.json`

Add this configuration (using the path you found in step 1):

```json
{
  "mcpServers": {
    "mcphub": {
      "command": "node",
      "args": ["/opt/homebrew/lib/node_modules/@mcphub/gateway/dist/src/mcphub-gateway.js"]
    }
  }
}
```

Note: Replace the path in `args` with your actual path from step 1.

### 3. Start Claude Desktop

Start or restart Claude Desktop

The gateway will automatically connect to the MCPHub server at `https://server.mcphub.ai/api/mcp`.

## Troubleshooting

1. If you can't find the gateway path:
   ```bash
   # List all global packages and look for @mcphub/gateway
   npm list -g
   
   # Or specifically check the gateway
   npm list -g @mcphub/gateway
   ```

2. Verify your Node.js installation:
   ```bash
   # Check Node version
   node --version
   
   # Check npm version
   npm --version
   ```

3. Common issues:
   - If using Homebrew on macOS, make sure Node.js is properly linked:
     ```bash
     brew doctor
     brew link node
     ```
   - If you get permission errors, you might need to use `sudo` for the installation

4. Check if the MCPHub server is accessible:
   - Try opening `https://server.mcphub.ai/api/mcp/health` in your browser

## License

[Apache 2.0 License](LICENSE)

## Support

If you encounter any issues or have questions:
- File an issue on GitHub

## Contributing

Contributions are welcome! Please feel free to submit a Pull Request.