Skip to main content
Glama
harpd-mcp

harpd-mcp

Official

harpd-mcp

Query Harpd's public AI product, ranking, research and evidence datasets directly from AI agents.

Powered by Harpd Data

CI License: MIT Data: CC BY 4.0 MCP

harpd-mcp is a Model Context Protocol server. It gives an AI agent 11 tools for reading Harpd's open datasets — 1,122 AI products, three Rank boards, 28 category boards, three Discovery Index slices, the AI Market Index, published research and the Evidence Graph — over stdio, with mandatory provenance on every single result.

git clone https://github.com/harpd-dev/harpd-mcp && cd harpd-mcp
npm install && npm run build
node examples/raw-stdio.mjs   # zero-dependency proof it works

The problem this solves

Harpd publishes its data openly at harpd.com/data and mirrors it to GitHub as raw JSON under CC BY 4.0. That is great for a developer who already knows the repository exists.

It is useless to an AI agent. An agent asked "which AI coding assistants are listed, and can you back that up?" cannot curl a URL it has never heard of. In practice the agent either says it has no data, or — far worse — answers from training-data recall and states a confident, unsourced, possibly stale fact about a product.

harpd-mcp closes that gap. It turns the datasets into callable tools, so the agent retrieves the current record instead of remembering one.

Related MCP server: FirstData MCP

Why it exists

Three design decisions separate this from "wrap a JSON file in a tool":

1. Provenance is not optional. Every response — the envelope and every record inside it — carries a provenance block with source, sourceUrl, dataset (the file path), updatedAt, license, attribution and evidence. There is no code path that returns a bare { name }. An agent that quotes Harpd data can always say where it came from, when it was published, and under what licence.

2. The two domain rules are encoded, not documented. They appear in the tool descriptions the model actually reads, in the server instructions, and in a machine-readable disclaimers array on every payload:

  • rankPoints are promotional placement bought with Credits on Harpd Rank. They are NOT an editorial quality score. Any tool that can order by rankPoints says so in its description and in its returned provenance.

  • There is no multi-month ranking history in the dataset repository. Harpd publishes three live period-scoped snapshots. get_ranking_history returns the periods that genuinely exist and states the limitation in the response itself. It will not fabricate a trend line.

3. Failure is graceful. A missing product or an unknown category returns a structured found: false payload listing the valid options — not a crash and not a stack trace in the model's context.

What data it uses

Read-only. Nothing is written back, and no API key is required.

Dataset file

Records

Served by

data/products/products.json

1,122

search_products, get_product, get_products

data/rankings/overall.json

1,122

get_rankings, get_ranking_history

data/rankings/monthly.json

1,122

get_rankings, get_ranking_history

data/rankings/weekly.json

1,122

get_rankings, get_ranking_history

data/rankings/categories.json

28

get_category_ranking

data/research/ai-market-index.json

27

get_research

data/research/ai-agent-index.json

334

get_ai_agents

data/research/ai-tools-index.json

693

get_ai_tools

data/research/developer-tools-index.json

1,918

get_developer_tools

data/research/research.json

5

get_research

data/evidence/evidence.json

5 claims

get_evidence

data/manifest.json

—

dataset metadata

Record counts are read from the datasets themselves at runtime, not hard-coded.

Scope note. The product catalog is 1,122 records (products.json and the three ranking boards). The research rows — ai-agent-index (334), ai-tools-index (693) and developer-tools-index (1,918) — are separate coverage slices of the Harpd Discovery Index, not the product catalog. They are different datasets with their own sizes; only the catalog rows must equal the canonical product count. Full input/output reference: docs/tools.md.

How to run it

Requires Node.js >= 18.17.

git clone https://github.com/harpd-dev/harpd-mcp
cd harpd-mcp
npm install
npm run build

Then point any MCP stdio client at node /absolute/path/to/harpd-mcp/dist/index.js.

Environment variables

Variable

Default

Purpose

HARPD_DATA_BASE

https://raw.githubusercontent.com/harpd-dev/harpd-ai-datasets/main/

Where to read datasets from. Supports https://, http:// and file:// (needs a trailing slash).

HARPD_CACHE_TTL_MS

3600000

On-disk cache TTL in milliseconds.

HARPD_CACHE_DIR

~/.cache/harpd-mcp

Cache location.

The server fetches datasets from HARPD_DATA_BASE at runtime and caches them on disk for the TTL. If a live fetch fails it falls back to the cached copy and adds a warning to the response. A file:// base bypasses the cache entirely so local runs are deterministic.

How to use the output

Every payload is one JSON text block shaped like this:

{
  "tool": "search_products",
  "found": true,
  "query": { "query": "coding", "limit": 2 },
  "pagination": { "total": 13, "count": 2, "offset": 0, "limit": 2, "hasMore": true, "nextOffset": 2 },
  "results": [
    {
      "product": { "id": "github-copilot", "name": "GitHub Copilot", "rank": 11, "rankPoints": 0, "…": "…" },
      "provenance": {
        "source": "Harpd",
        "sourceUrl": "https://raw.githubusercontent.com/…/data/products/products.json",
        "dataset": "data/products/products.json",
        "datasetId": "products",
        "updatedAt": "2026-09-15T03:58:43.395Z",
        "license": "CC BY 4.0",
        "attribution": "Harpd (https://harpd.com)",
        "evidence": {
          "claimIds": [],
          "methodologyUrl": "https://harpd.com/rank/methodology/",
          "citation": "Harpd. \"products dataset.\" https://harpd.com/data/ Accessed: 2026-09-15. License: CC BY 4.0."
        },
        "notes": ["rankPoints are promotional placement bought with Credits on Harpd Rank. They are NOT an editorial quality score, …"]
      }
    }
  ],
  "provenance": { "…": "same block, envelope level" },
  "disclaimers": ["rankPoints are promotional placement bought with Credits on Harpd Rank. …"]
}

Practical guidance:

  • Quote provenance.sourceUrl and provenance.updatedAt whenever the agent repeats a figure. That is the difference between a sourced answer and a guess.

  • Respect disclaimers. They are returned precisely so they can be surfaced.

  • Page with pagination.nextOffset, not by guessing offsets. limit is capped at 200 by the input schema.

  • Do not read rankPoints as quality. If you need a non-purchasable signal, Harpd publishes one separately at harpd.com/data and says so in the Evidence Graph.

Tools

Tool

Purpose

search_products

Free-text / category search over the product catalog.

get_product

One product by id, slug or name.

get_products

Paginated catalog listing with filters.

get_rankings

A Rank board (overall / monthly / weekly) with its period metadata.

get_category_ranking

One of the 28 category boards, with board stats.

get_ranking_history

Compare the three board snapshots — and be told there is no time series.

get_ai_agents

AI-agent coverage slice (334 records).

get_ai_tools

AI-tools coverage slice (693 records).

get_developer_tools

Developer-tools coverage slice (1,918 records).

get_research

Monthly research reports + the AI Market Index.

get_evidence

The Evidence Graph: claims, chain, rules, and what Harpd does not claim.

Client configuration

Verification status. This repository has verified the generic stdio client configurations below by actually running them (see examples/ — raw-stdio.mjs speaks raw JSON-RPC with zero dependencies, and examples 1–5 use the official MCP SDK stdio client). The Claude Desktop, Cursor and VS Code sections are provided as configuration templates but are not verified in this repo — those applications were not available to launch and drive here, so no compatibility claim is made. Verify them yourself before relying on them.

Use absolute paths. Most clients do not inherit your shell PATH.

Generic stdio client — VERIFIED in this repo

Any client that can spawn a process and speak MCP over stdio:

{
  "command": "node",
  "args": ["/absolute/path/to/harpd-mcp/dist/index.js"],
  "env": {
    "HARPD_DATA_BASE": "https://raw.githubusercontent.com/harpd-dev/harpd-ai-datasets/main/"
  }
}

Verified two ways:

# 1. Raw JSON-RPC over stdio, zero dependencies (no MCP client library at all)
node examples/raw-stdio.mjs

# 2. Official MCP SDK stdio client
node examples/01-top-ai-coding-tools.mjs

Both were run against dist/index.js and returned real tool results. See the Verification section for the exact output.

If you prefer the published package shape, the bin entry is harpd-mcp, so once the package is published on npm the equivalent config is:

{ "command": "npx", "args": ["-y", "harpd-mcp"] }

This package is not published to npm yet, so use the absolute-path form above for now. Publishing is a separate step and is not claimed here.

Claude Desktop — NOT VERIFIED in this repo

Config file: ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows).

{
  "mcpServers": {
    "harpd": {
      "command": "node",
      "args": ["/absolute/path/to/harpd-mcp/dist/index.js"],
      "env": {
        "HARPD_DATA_BASE": "https://raw.githubusercontent.com/harpd-dev/harpd-ai-datasets/main/"
      }
    }
  }
}

Restart Claude Desktop after editing. The 11 tools appear under the tools icon.

Cursor — NOT VERIFIED in this repo

Project config .cursor/mcp.json, or global ~/.cursor/mcp.json:

{
  "mcpServers": {
    "harpd": {
      "command": "node",
      "args": ["/absolute/path/to/harpd-mcp/dist/index.js"]
    }
  }
}

VS Code — NOT VERIFIED in this repo

Workspace config .vscode/mcp.json. Note that VS Code uses servers, not mcpServers:

{
  "servers": {
    "harpd": {
      "type": "stdio",
      "command": "node",
      "args": ["/absolute/path/to/harpd-mcp/dist/index.js"]
    }
  }
}

Running offline

Point HARPD_DATA_BASE at a local checkout of the datasets. file:// bases need a trailing slash:

git clone https://github.com/harpd-dev/harpd-ai-datasets
HARPD_DATA_BASE=file:///absolute/path/to/harpd-ai-datasets/ node dist/index.js

Verification

Everything below was run in this repository. The test suite runs against the real dataset files, never fixtures:

HARPD_DATA_BASE=file:///Users/shankou/harpd/harpd-ai-datasets/ npm test
#  Test Files  2 passed (2)
#       Tests  84 passed (84)

Data Source

This server reads those files at runtime from https://raw.githubusercontent.com/harpd-dev/harpd-ai-datasets/main/. It ships no dataset copy of its own, so it cannot serve data that Harpd has not published.

Harpd Open AI Data Ecosystem

harpd-mcp is one client of the same open dataset that powers the rest of the Harpd data surface. If you need the raw files, the CSV exports, the JSON Schemas or the monthly snapshots, go straight to the source.

  • Harpd data portal — harpd.com/data — the canonical, citable entry point for every published dataset.

  • Harpd AI Datasets (GitHub) — github.com/harpd-dev/harpd-ai-datasets — raw JSON + CSV, JSON Schemas, validation scripts, starter templates and copy-paste examples in Python, JavaScript, curl, DuckDB, pandas and SQL.

  • Harpd Rank — harpd.com/rank — the boards these rankings come from, plus the published methodology.

  • Harpd Evidence — harpd.com/evidence — every published claim resolved to its evidence, dataset, methodology, source and timestamp.

  • Harpd research — harpd.com/research — the monthly index reports.

  • Harpd Discovery — harpd.com/discovery — the Product Discovery Index the agent / AI tools / developer tools slices are cut from.

  • harpd-mcp — this repository — the agent-facing MCP server for all of the above.

If you are building with the raw files rather than through an agent, use the datasets repository directly: it carries CSV exports, schemas and a daily sync workflow that this server does not duplicate.

Citation

If you use this server or the data behind it, cite Harpd:

@misc{harpd_data_2026,
  title        = {Harpd AI Datasets},
  author       = {{Harpd}},
  year         = {2026},
  howpublished = {\url{https://harpd.com/data/}},
  note         = {Open datasets for AI products, rankings, research and evidence.
                  License: CC BY 4.0. Mirror: \url{https://github.com/harpd-dev/harpd-ai-datasets}}
}

Plain text attribution string, as embedded in every dataset file:

Data from Harpd (https://harpd.com/)

If you cite this server specifically:

@software{harpd_mcp_2026,
  title  = {harpd-mcp: Model Context Protocol server for Harpd open AI datasets},
  author = {{Harpd}},
  year   = {2026},
  url    = {https://github.com/harpd-dev/harpd-mcp},
  note   = {MIT licensed. Data licensed CC BY 4.0 by Harpd.}
}

Machine-readable citation metadata is in CITATION.cff.

Development

npm run build   # tsc -> dist/
npm run lint    # eslint
npm test        # vitest, against the real datasets

See CONTRIBUTING.md and SECURITY.md.

License

  • Code: MIT — see LICENSE.

  • Data served by this server: CC BY 4.0, © Harpd. Attribution required. The MIT licence on this repository does not relicense the data.

Harpd is not affiliated with Anthropic, Cursor or Microsoft. MCP client names are used only to describe configuration formats.

Available Tools

11 tools
get_ai_agentsGet AI agents from the Harpd Discovery IndexA
Read-only

Return AI-agent products from the Harpd AI Agent Index (334 records, Discovery Index slice where category = "agents"). This is a COVERAGE list derived from the Harpd Product Discovery Index, NOT a ranking: records carry no rank and no rankPoints, and their order implies nothing about quality. Each record includes its observed_at timestamp, discovery source and profile URL. Use this to find AI agent products, their domains, one-line titles and where they were discovered. Some records also appear on the Harpd Rank board (on_rank_board). Every record carries full provenance (source, dataset path, sourceUrl, updatedAt, license, attribution).

Inputs: limit, query, domain, offset, +3 more.

get_ai_toolsGet AI tools from the Harpd Discovery IndexA
Read-only

Return AI tooling products from the Harpd AI Tools Index (693 records, Discovery Index slice where category is "agents" or "ai-media"). This is a COVERAGE list derived from the Harpd Product Discovery Index, NOT a ranking: records carry no rank and no rankPoints, and their order implies nothing about quality. Each record includes its observed_at timestamp, discovery source and profile URL. Use this to retrieve the current AI tools dataset: name, domain, URL, category, title, description, discovery source and observation timestamp. Every record carries full provenance (source, dataset path, sourceUrl, updatedAt, license, attribution).

Inputs: limit, query, domain, offset, +3 more.

get_category_rankingGet a Harpd category boardA
Read-only

Read one of the 28 published Harpd Rank category boards: the board metadata (product counts, state, board URL) plus the products listed in that category. CRITICAL: rankPoints are promotional placement bought with Credits on Harpd Rank, NOT an editorial quality score. A category board being "topRankOpen" or a product having high rankPoints says nothing about product quality. An unknown category returns a structured found:false result listing the valid slugs, not an error. Every record carries full provenance.

Inputs: category (required), sort, limit, offset.

get_developer_toolsGet developer tools from the Harpd Discovery IndexA
Read-only

Return developer-tool products from the Harpd Developer Tools Index (1,918 records, Discovery Index slice where category = "developer"). This is a COVERAGE list derived from the Harpd Product Discovery Index, NOT a ranking: records carry no rank and no rankPoints, and their order implies nothing about quality. Each record includes its observed_at timestamp, discovery source and profile URL. Use this to find developer tools, SDKs, infra and dev platforms by name, domain or description. Every record carries full provenance (source, dataset path, sourceUrl, updatedAt, license, attribution).

Inputs: limit, query, domain, offset, +3 more.

get_evidenceGet Harpd evidence claims for a dataset or productA
Read-only

Query the Harpd Evidence Graph: every published Harpd claim resolved to its evidence, dataset, methodology, source and data timestamp, including the claims Harpd explicitly does NOT make. Use this to check whether a statement about Harpd data is actually supported before repeating it. IMPORTANT: the graph itself records that rankPoints are promotional placement bought with Credits, and that "a higher-ranked product is a better product" is NOT a supported claim. rankPoints are NOT an editorial quality score. Claims that fail the evidence chain are returned with their violations rather than hidden. Every record carries full provenance.

Inputs: limit, query, offset, claimId, +4 more.

get_productGet one Harpd AI productA
Read-only

Look up a single product in the Harpd open product catalog by id, slug or name. Returns the product record plus mandatory provenance (source, dataset path, sourceUrl, updatedAt, license, attribution, evidence links). A product that does not exist returns a structured found:false result rather than an error. NOTE: rankPoints are promotional placement bought with Credits, NOT an editorial quality score.

Inputs: id, name, slug.

get_productsList Harpd AI products (paginated)A
Read-only

Page through the full Harpd open product catalog (1,122 records) with filters on category, verification state, product type and rankPoints range. Use this to enumerate or bulk-export products; use search_products for free-text lookup. IMPORTANT: rankPoints are promotional placement bought with Credits on Harpd Rank, NOT an editorial quality score. Sorting by "rankPoints" orders by promotional placement, not by merit. Page size is capped at 200. Every record carries full provenance.

Inputs: sort, limit, offset, category, +4 more.

get_ranking_historyCompare Harpd board snapshots (NOT a time series)A
Read-only

Compare the three published Harpd Rank board snapshots (overall / monthly / weekly) for one product, or side by side at board level. HONEST SCOPE WARNING: this repository publishes three LIVE period-scoped snapshots, each covering its current window. It does NOT contain a multi-month historical time series, so this tool cannot and will not return month-over-month trends. It returns the periods the datasets really expose plus an explicit statement of the limitation. CRITICAL: rankPoints are promotional placement bought with Credits on Harpd Rank, NOT an editorial quality score. Movement between boards reflects promotional placement, not a change in product quality.

Inputs: top, boards, productId, productSlug.

get_rankingsGet a Harpd Rank boardA
Read-only

Read one of the three published Harpd Rank boards (overall / monthly / weekly) with its period metadata. CRITICAL: rankPoints are promotional placement bought with Credits on Harpd Rank. They are NOT an editorial quality score, and a higher rankPoints value does NOT mean a better product. Ordering by "rankPoints" orders by promotional placement. Ordering by "rank" follows the published board position, which is also derived from promotional placement. The board is a live snapshot for its period, not a historical time series. Every record carries full provenance.

Inputs: sort, board, limit, offset, +1 more.

get_researchGet Harpd research reports and the AI market indexA
Read-only

Read Harpd research output: the published monthly research reports (5 records, one per family/month) and the AI Market Index (27 category rows with product counts, product share and rank-point share). IMPORTANT: pointsShare is a share of rankPoints, and rankPoints are promotional placement bought with Credits on Harpd Rank. They are NOT an editorial quality score. pointsShare is not a share of quality or of market merit. Reports exist only for closed months with enough ranked products in the family scope. Every record carries full provenance.

Inputs: limit, family, offset, section, +2 more.

search_productsSearch Harpd AI productsA
Read-only

Search the Harpd open product catalog (1,122 AI products) by free text, category and verification state. Returns each product with its board position (rank) and its rankPoints. IMPORTANT: rankPoints are promotional placement bought with Credits on Harpd Rank, NOT an editorial quality score. Ordering by rankPoints orders by promotional placement, not by merit. Every record carries full provenance (source, dataset path, updatedAt, license, attribution, evidence).

Inputs: sort, limit, query, offset, +2 more.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A4.2/5.0

    Scored across 11 tools

    Disambiguation4/5

    The catalog tools are clearly separated by mode (single lookup, free-text search, paged enumeration), and ranking, discovery-index, research, and evidence tools target distinct resources. The main overlap is between get_ai_agents and get_ai_tools, since one is a subset of the other's filter scope, but the descriptions do enough to clarify their different index purposes.

    Naming Consistency4/5

    The naming pattern is mostly predictable: a get_ prefix followed by a domain noun, with search_products as the one clear exception. There is also some singular/plural inconsistency (get_product vs get_products, get_rankings vs get_category_ranking), but the overall convention remains readable and navigable.

    Tool Count5/5

    Eleven tools is well within the ideal range and each tool maps to a meaningful data-access need: product lookup/search/enumeration, board reads, history comparison, three discovery-index slices, research, and evidence checking. None of the tools feel redundant or superfluous for the server's stated purpose.

    Completeness4/5

    The server covers the core read-only workflows for the Harpd domain: retrieving products, searching and enumerating them, reading rank boards, comparing snapshots, pulling discovery-index slices, and accessing research and evidence. Minor gaps include the lack of a dedicated category-list endpoint and the absence of search/detail operations within the discovery-index slices, but these are workable.

    Maintenance

    ActivityMaintained
    ResponsivenessLimited data

    Related MCP Connectors

    Related MCP Servers

    • F
      license
      Not graded
      quality
      A
      maintenance
      Enables users and AI agents to turn natural-language data queries into authoritative primary-source recommendations, complete with authority levels, access URLs/APIs, and step-by-step website navigation for retrieving verifiable data.
      -
    • F
      license
      Not graded
      quality
      A
      maintenance
      Enables users and AI agents to turn natural-language data questions into vetted authoritative source recommendations, with step-by-step website navigation, API details, and traceable evidence paths to primary data.
      -
    • F
      license
      Not graded
      quality
      A
      maintenance
      Enables users and AI agents to turn natural-language factual queries into recommended authoritative data sources and guided navigation paths for retrieving original datasets, APIs, and documents with verifiable evidence chains.
      -
    • F
      license
      Not graded
      quality
      A
      maintenance
      Enables AI agents and users to turn natural-language data questions into recommended authoritative primary sources and detailed, verified website/API retrieval paths with traceable evidence chains.
      -