The Rfp Hub MCP Server

RFP Hub

An open, neutral aggregation layer and standard for Ethereum-ecosystem funding opportunities — grants, hackathons, bounties, accelerators, VC funds, and RFPs. It indexes, verifies, and distributes opportunities through a standard format, a public API, open data exports, and agent-friendly tooling (M2 ships these as running, tested code) — and where an entry carries an application link, it sends you to the opportunity's own submission channel to apply. (Carrying one is ingestion policy on the Hub's own data, with named exceptions — four of the 142 seeded entries have no public application URL, each documented in the API README; the schema itself leaves applicationUrl optional, so third-party documents may omit it.)

That link (applicationUrl) is the single link-back target in the standard, and it carries whatever the submission channel actually is — an application portal, a form, or a forum thread where no portal exists. The Hub is where you find the opportunity, never where you apply.

pnpm monorepo. The hand-authored JSON Schema is the single source of truth; TypeScript types are generated from it, and every other format the standard does or doesn't ship is listed in ARTIFACTS.md.

The Standard

The heart of the project is the RFP Hub Standard — a versioned, documented, validated JSON Schema (draft 2020-12) describing a funding opportunity. It's published as @the-rfp-hub/standard (CC0-1.0) and ships generated TypeScript types.

• Schema: packages/standard/schemas/v1.0.0/opportunity.schema.json
• Field reference: FIELDS.md
• Status of this version (maturity, known issues): STATUS.md
• Prior-art crosswalk (DAOIP-5 · schema.org/Grant): CROSSWALK.md
• Validated against real-world funding data: BENCHMARK.md
• What's normative vs. informative: NORMATIVE.md

Validate anything against it:

npx rfphub-validate opportunity.json

Packages

Every package takes its contract from @the-rfp-hub/standard alone, and never reaches into another package's internals (dependency inversion at the package level). The only non-Standard cross-package dependency is packages/api → rfphub-validate, through that package's published API, so the Hub validates with the same reference implementation everyone else runs.

Two version axes. A package's version is its npm distribution version and moves freely; the spec version (1.0.0, in specVersion and the schema $id) is the data contract and moves only under PROCESS.md. They are different numbers on purpose.

Governance

The standard is governed by written process, not by whoever is around:

• GOVERNANCE.md — editors, the decision rule, review windows, appeals, non-discrimination and ranking (what decides indexing, what never does, and why there is no paid placement), and the list of things this project deliberately does not have.
• REVIEW-CRITERIA.md — what a reviewer checks on a single submitted listing, what is explicitly not a criterion, what "pending" means, and who decides.
• PUBLISHERS.md — how an organization becomes a verified publisher, claims an entry, and how verification is revoked.
• packages/standard/PROCESS.md — feature stages, what "breaking" means operationally, deprecation, how to register a vocabulary value, the RFC process routing table, the release checklist.
• adr/ — the decision records behind the shape of the data model.

Guides

docs/ holds the handoff guides — four documents, each written for one person doing one job, linking to the per-package detail rather than duplicating it:

• docs/deployment.md — what runs where, what must exist in the cloud account before the first deploy (there is no infrastructure-as-code), the required variables, the first-deploy sequence, rollback, the manual npm release runbook, and the three ways to deploy a copy of the frontend.
• docs/api-integration.md — a five-minute read-only quickstart, the write flow from an email address to a publishing key, the scope table, and the nine contracts that surprise integrators.
• docs/publisher-onboarding.md — for whoever operates the Hub: running a publisher application end to end, refusing one, revoking verification, and deciding a disputed claim.
• docs/external-deploy-test.md — the two-hour protocol that proves an outside developer can deploy a frontend against the public API from the docs alone.

Every shell block in those guides is marked no-run, safe-read or staging-write; the convention is defined in docs/README.md.

Deploy your own copy, or install the skill

Deploy your own copy of the frontend with the one-click Deploy Button in packages/frontend/README.md. It lives in exactly one place on purpose — a Deploy Button URL carries the whole build configuration in its query string, so a second copy of the button is a second configuration that drifts. The other two paths, and the read-only limitation every copy inherits, are in docs/deployment.md §9.

Install the agent skill through any of three channels, all of which install the same directory:

# 1. multi-agent installer: detects the agents you have and copies the skill into each
npx skills add The-RFP-Hub/the-rfp-hub --skill funding-search

# 2. Claude Code plugin marketplace
claude plugin marketplace add The-RFP-Hub/the-rfp-hub
claude plugin install rfp-hub@rfp-hub

# 3. a plain copy into whichever agent's skill directory applies
cp -R skills/funding-search ~/.claude/skills/

Every agent's directory, with the citation for each, is in skills/README.md.

Repo topology

Developed as one pnpm workspace for fast iteration (the schema and its generated types move together in a single change), and published as independent npm packages. At handoff the packages can be split into per-component repos (the-rfp-hub/standard, the-rfp-hub/validate, …) via git subtree split. The per-package LICENSE, README and package.json provide the metadata for a future split. Before splitting, replace workspace:* dependencies with registry ranges and verify standalone install, build and test; packages/api is not published.

Develop

pnpm install
pnpm codegen        # regenerate TS types from the JSON Schema
pnpm codegen:check  # fail if generated types drift from the schema (CI gate)
pnpm build          # build all packages
pnpm test           # run the test suite (vitest)
pnpm typecheck
pnpm lint           # biome

Already have a dev database from M2? It needs one upgrade before the current migrations will apply. packages/api/docker-compose.yml now pins pgvector/pgvector:pg15 instead of postgres:15-alpine, because CREATE EXTENSION vector ships as a migration. Same major version, so the data directory is compatible and the named volume is reused — but the C library underneath changes with the image, and with it the collation provider. Run the script; it dumps first, refreshes the collation version, reindexes, migrates, and compares row counts before and after:

packages/api/scripts/upgrade-dev-postgres.sh

It takes no arguments and refuses anything resembling down -v, because the one-word-shorter version of this operation destroys the seeded dev corpus. Details, and the escape hatch if the collation change causes trouble, are in packages/api/README.md.

Verifying a deployment

Completion criteria are checkable rather than assertable, and there are two tools because there are two kinds of criterion.

scripts/check-deployment.mjs only reads. Health and TLS, every operation in the published OpenAPI document executed against the live service (including the strict-400 negative contract), every served document validated against the Standard, and the CC0 export's freshness and latest.json/latest.csv pair invariant:

pnpm check:deployment --milestone m2 --api https://api.example.org --export-url https://data.example.org

Pass/fail per criterion on stdout, a JSON report alongside, non-zero exit on any failure. Nothing about a particular host or dataset is baked in, and the tool holds no credential flag at all — which is what makes it safe to point at production, where its defaults already point. Run it by hand, or from any external runner, against whichever deployment you want an answer about.

The nightly publishing job runs exactly this, against the deployment and the export it has just pushed, and fails if it does not pass — so the job going green means published and independently verified, not merely "ran". See Open data.

scripts/accept-writes.mjs writes, which is the other half: the publisher lifecycle, the review queue, the audit trail, duplicate detection, source verification, publisher analytics and the staleness job:

pnpm accept:writes --milestone m3 --api https://api-staging.example.org \
  --namespace my-org --session-token "$SESSION" --admin-token "$ADMIN"

Because it writes, it refuses far more. The target must be loopback or an explicitly allowlisted staging origin, over https, with the redirect chain re-checked — there is no flag that forces production. It refuses to start without a namespace, a publisher credential and a reviewer credential, the last because its teardown rejects and unlists everything the run created and a run that cannot clean up after itself has no business writing. Everything it creates is prefixed compliance-. It is deliberately not wired into CI — CI has no deployment to write to, and a sign-off tool needing a standing publisher credential in repository secrets would be a worse thing to have than a tool somebody runs.

Both tools, their criteria and their exit codes: scripts/compliance/README.md.

The same read-only tool covers governance, the reference frontend, the MCP server, the agent skill and the handoff docs:

pnpm check:deployment --milestone m4 --site https://ethrfps.app --api https://api.ethrfps.app --browser

The one case that could look like a write — submit_opportunity's fail-closed behavior — runs against a local recording server the checker starts itself, never against --api. Pass --browser for the checks that need a rendered page (search/filter/pagination, /publishers, the three responsive viewports); without it those requirements are reported unmet, which makes their criterion incomplete and the run exit non-zero. --offline applies to the docs criterion only, so the combination that means anything is --only docs --offline — a docs lint, labeled as such and never a deployment sign-off.

The write side has a second profile, staging only, which drives the real MCP submit_opportunity interlock end to end — preview, an out-of-band rfphub-mcp approve, commit — and tears the fixture down afterwards:

pnpm accept:writes --milestone m4 --api https://api.staging.example.org \
  --session-token "$REVIEWER_SESSION" --api-key "$RFPH_KEY"

The same three credential flags as the publisher profile, under the same target guard: a session whose account may review (or an --admin-token), because the teardown rejects the entry, and the write-scoped rfph_ key the MCP server submits with. No run without both.

Open data

The dataset is published to exports/ on the default branch by a scheduled workflow (.github/workflows/nightly-export.yml), under CC0-1.0. No bucket and no credentials: the files are served directly, over TLS, from the repository, and every snapshot is a commit, so what the dataset said on any past day is git log.

https://raw.githubusercontent.com/The-RFP-Hub/the-rfp-hub/main/exports/latest.json
https://raw.githubusercontent.com/The-RFP-Hub/the-rfp-hub/main/exports/latest.csv
https://raw.githubusercontent.com/The-RFP-Hub/the-rfp-hub/main/exports/latest.manifest.json

latest.json and latest.csv are two independently named mutable files, so a consumer fetching both can, rarely, catch one of each run. latest.manifest.json is the answer to that: it is replaced by a single atomic operation, and it names both archives by immutable, content-addressed filenames with the full sha256 of each. Resolve it once, fetch what it names, hash the bytes, compare — and the pair is provably one run's rather than assumed to be.

The publishing job sources its data from the live API rather than from a database, validates every record against the Standard before writing anything, and refuses to publish a dataset that is empty, short, or inconsistent with what /v1/stats reports.

If you want the dataset as of right now rather than as of last night, the API serves the same thing live, in one call, from the same serializer — GET /v1/export/opportunities.json and GET /v1/export/opportunities.csv. The trade is deliberate: a live download is current but anonymous, while a nightly snapshot is up to a day old and verifiable — immutable, digest-named, and vouched for by the manifest. Build a pipeline on the snapshot; reach for the endpoint when you want today's answer. See packages/api/README.md for the file layout, the manifest contract and the guarantees each one carries.

Using the API

Runnable client examples — curl, TypeScript (zero-dependency fetch), and Python (stdlib-only) — live in examples/, one endpoint-by-endpoint tour each. All three read the API's base URL from RFPHUB_API_BASE (default http://localhost:3001); see packages/api/README.md to run one locally.

The TypeScript example installs @the-rfp-hub/standard from npm and types its responses with it, so it doubles as a type-contract demo — CI clean-installs and typechecks it the way a consumer would. That step covers the TypeScript client only: it makes no request, does not read the curl or Python examples, and resolves the standard from the registry, so it catches a published release that breaks a consumer, not a change to packages/standard in this repo.

Two syndication feeds — /v1/feeds/opportunities.atom (Atom 1.0) and /v1/feeds/opportunities.rss (RSS 2.0) — publish the most recent opportunities for any reader or bot that would rather subscribe than poll JSON; both are ETag-validated, so a poller that sends If-None-Match gets a 304. See packages/api/README.md.

The API's list query contract is strict — an undefined parameter or an out-of-enum value is a 400, never a silently unfiltered 200 — so the examples show a typo failing loudly.

Publishing to the Hub

Reading is public and unauthenticated, and stays that way. Writing is authenticated, and the credential you hold decides not only whether a submission is accepted but whether it goes live:

API=https://api.ethrfps.app

# Who am I, and what may I do?
curl -H "Authorization: Bearer $TOKEN" $API/v1/me

# Mint a publishing key. The secret is in this response and nowhere else, ever.
curl -X POST -H "Authorization: Bearer $TOKEN" -H 'content-type: application/json' \
  -d '{"name":"programme-sync","scopes":["read","write","publish"]}' $API/v1/keys

# Submit. Live on arrival only if the key carries `publish` AND the account is a verified member
# of the namespace in the entry's id; otherwise it is stored and queued for review.
curl -X POST -H "Authorization: Bearer $KEY" -H 'content-type: application/json' \
  --data-binary @opportunity.json $API/v1/opportunities

Two credential kinds share one header: a signed-in session, and a long-lived scoped API key (rfph_…). Which one you present decides real authority — keys are refused outright on the routes that manage credentials, change account identity, review or administer, so a leaked key cannot mint a stronger one. The tiers, the scopes, the per-route matrix and the reasoning are in packages/api/docs/auth.md.

To publish under your own namespace without review, apply as a verified publisher: PUBLISHERS.md is the whole process — what qualifies, what is checked, what approval grants, and how it is revoked.

Beyond the public read surface, the API serves:

Every mutation — by a person, a key, or a job — writes a row to an append-only trail enforced by a database trigger, and the trail for any entry is publicly readable.

The nightly maintenance jobs that close past-due and long-abandoned listings, roll up analytics and backfill source checks are documented, schedule and runbook, in packages/api/docs/jobs.md. They run as one task on the deployed image — node packages/api/dist/jobs.js all runs the whole chain in order in one process — which is scheduled outside this repository and runs before the open-data export, which publishes on its own cron; nothing here schedules it, and an operator who needs a job run outside that starts the same one-off task by hand.

Licensing

Code is MIT; the standard and datasets are CC0-1.0. See LICENSING.md for the per-path breakdown.

Contributing

See CONTRIBUTING.md and our Code of Conduct. Security issues: SECURITY.md.