npm package: @one-source/docs-mcp
Description: MCP server for OneSource Web3 API documentation — search docs, explore GraphQL schema, find examples
Author: BlockParty
Latest version: 4.0.3

# onesource-docs-mcp

[![npm version](https://img.shields.io/npm/v/onesource-docs-mcp)](https://www.npmjs.com/package/onesource-docs-mcp)
[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](./LICENSE)
[![Node >= 18](https://img.shields.io/badge/node-%3E%3D18-brightgreen)](https://nodejs.org)

Give your AI assistant full access to the [OneSource Web3 API](https://docs.onesource.io) documentation — search docs, explore the GraphQL schema, and find working query examples for Ethereum, Base, Optimism, Avalanche, Sepolia, and Shape.

> **What is MCP?** The [Model Context Protocol](https://modelcontextprotocol.io) lets AI assistants call tools and access data sources. This server exposes OneSource documentation as 10 read-only tools — no API key or authentication needed.

## Quick Start

### Remote (zero setup)

Point any MCP client at the hosted endpoint — no install required:

```
https://docs.onesource.io/api/mcp
```

### Claude Desktop

Add to your `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "onesource-docs": {
      "command": "npx",
      "args": ["-y", "onesource-docs-mcp"]
    }
  }
}
```

### Claude Code

```bash
claude mcp add onesource-docs -- npx onesource-docs-mcp
```

### Any MCP Client (stdio)

```bash
npx onesource-docs-mcp
```

### HTTP Server (self-hosted)

```bash
npx onesource-docs-mcp --http
npx onesource-docs-mcp --http --port=8080
```

Then connect your MCP client to `http://localhost:3001/mcp`.

## Tools

| Tool | Purpose | When to use |
|------|---------|-------------|
| `search_docs` | Keyword search across all documentation | Finding guides, concepts, or API patterns |
| `get_query_reference` | Full reference for a root GraphQL query | Building a specific query with correct args/filters |
| `get_type_definition` | Schema definition for any type/enum/input | Understanding field shapes and return types |
| `list_examples` | Browse or search working GraphQL examples | Finding ready-to-use query patterns |
| `list_supported_chains` | All supported blockchain networks + endpoints | First question: "What chains are supported?" |
| `get_filter_reference` | Filter fields and operators for a list query | Building filtered queries with correct syntax |
| `get_pagination_guide` | Cursor-based pagination pattern with examples | Implementing pagination for list queries |
| `get_schema_overview` | High-level summary of the entire schema | Exploring the API surface before diving in |
| `get_authentication_guide` | API key format, headers, and endpoints | Setting up authentication for the first time |

### search_docs

Search all OneSource documentation by keyword. Returns the top 5 matching sections with relevance scores.

```json
{ "query": "NFT metadata" }
```

### get_query_reference

Get the full reference for a root GraphQL query — arguments, filters, and return type.

Available queries: `address`, `addresses`, `block`, `blocks`, `contract`, `contracts`, `nft`, `nfts`, `token`, `tokens`, `transaction`, `transactions`.

```json
{ "query_name": "transactions" }
```

**Example output:**

```
# transactions

Query transactions with filtering and pagination.

Returns: [Transaction] (non-null)

Arguments:
  - `filter`: `TransactionFilter` — Filter criteria for transactions
  - `first`: `Int` = 10 — Number of results to return
  - `after`: `String` — Cursor for pagination
  ...
```

### get_type_definition

Get the schema definition for any GraphQL type, enum, scalar, input, or interface.

```json
{ "type_name": "Transaction" }
```

### list_examples

List all available examples, or search by topic. Without a `topic`, returns a summary listing of all examples. With a `topic`, returns full example content matching that keyword.

```json
{ "topic": "token transfers" }
```

Call with no arguments to browse all available examples:

```json
{}
```

### list_supported_chains

List all blockchain networks supported by OneSource with endpoint URLs and chain slugs.

```json
{}
```

### get_filter_reference

Get all filter fields and range operators for a specific list query.

```json
{ "query_name": "transactions" }
```

### get_pagination_guide

Get the cursor-based pagination pattern with step-by-step flow and common mistakes. Optionally pass a query name.

```json
{ "query_name": "tokens" }
```

### get_schema_overview

Get a high-level summary of the entire GraphQL schema — all queries, types, enums, interfaces, and scalars at a glance.

```json
{}
```

### get_authentication_guide

Get the full authentication guide — API key format, endpoint pattern, required headers, and common mistakes.

```json
{}
```

## Troubleshooting

**Tools return "Data files may be missing"**
The `data/` directory wasn't included in the install. Try `npm install onesource-docs-mcp` again, or if developing locally, run `npm run build:plugin` from the repo root.

**`npx onesource-docs-mcp` hangs with no output**
That's normal — stdio mode waits for JSON-RPC input on stdin. Use `--http` if you want an HTTP server you can curl.

**Port already in use**
Another process is using port 3001. Specify a different port: `npx onesource-docs-mcp --http --port=8080`

**"Type not found" even though it exists**
Type names are case-insensitive but must match the GraphQL name (e.g. `Transaction`, not `transaction_type`). The tool will suggest close matches if it can't find an exact match.

## What's New in v2

- **Factory pattern** — single `createMcpServer()` entry point shared across stdio, HTTP, CLI, and Vercel
- **HTTP transport** — run as a standalone HTTP server with `--http` flag
- **CLI entry point** — `npx onesource-docs-mcp` just works, with `--port` support
- **Remote endpoint** — hosted at `https://docs.onesource.io/api/mcp` (zero setup)
- **Pre-built data** — schema and docs are bundled in the package, no build step needed after install

## About

**Maintainer:** [BlockParty](https://github.com/BlockPartyDev)
**Repository:** [1s-developer-docs](https://github.com/BlockPartyDev/1s-developer-docs/tree/develop/scripts/mcp-server)
**Security:** All tools are read-only — no authentication, no writes, no API keys required.

## Development

```bash
# From repo root
npm run build:plugin    # Build everything (skills + schema data + MCP server)
npm run build:mcp       # Build MCP server only

# Test locally
node scripts/mcp-server/dist/server.js        # stdio (dev mode)
node scripts/mcp-server/dist/http-server.js   # HTTP on :3001
```

## License

MIT