fabrica-mcp: Instructions file for Codex

Fabrica MCP Server

An MCP server giving AI agents read-only access to tokenized real property data on the Fabrica protocol.

What is Fabrica?

Fabrica tokenizes real property (land) as ERC-1155 NFTs on Ethereum. A legal trust holds title at the county level, and the token represents the beneficial interest in that trust: owning the token means owning the beneficial interest in the trust that holds the property.

• Platform: https://fabrica.land
• Docs: https://docs.fabrica.land
• Company overview: https://about.fabrica.land
• Dune: https://dune.com/fabrica/dashboard

Project Structure

src/
  config.ts           # Network config, contract addresses, legal notices
  server.ts           # createServer(): registers every tool
  prompts.ts          # MCP prompts (due_diligence, work_parcel_list, wallet_review, how_to_add_land)
  index.ts            # stdio entrypoint (local installs)
  http.ts             # stateless Streamable HTTP handler (hosted)
  usage-log.ts        # one structured log line per request, no arguments or IPs (docs/usage/)
  vercel.ts           # Vercel function entry, bundled by scripts/build-vercel.mjs
  auth/
    config.ts         # Connect Fabrica (OAuth resource server): FABRICA_OAUTH flag, issuer per network, the /mcp/account resource
    token.ts          # access-token checks (ES256 JWT, issuer, audience, expiry, at+jwt) against the issuer's JWKS; never logged
  ui/property-card.ts # registers the property card MCP App resource (ui://fabrica/property-card)
  ui/generated/       # gitignored: HTML built from /ui by scripts/build-ui.mjs
server.json, server.testnet.json # MCP Registry entries (land.fabrica/mcp, land.fabrica/mcp-testnet); npm run registry:publish
skills/fabrica/SKILL.md # Agent Skills file, served at /skill.md by scripts/build-vercel.mjs; keep it in step with the tools
ui/
  property-card/      # the MCP App view (index.html template + app.ts), bundled with the
                      # MCP Apps SDK into one self-contained HTML string (no CDN scripts).
                      # view.ts: layout from the host context (compact under 480 px or on a
                      # phone, regular otherwise), hover, safe areas, fact lines; unit tested
  fonts/              # Open Sauce Two (OFL) subset, served at /fonts by the hosted server
  tools/
    properties.ts     # search_land, get_land_property, get_land_boundary
    lending.ts        # get_fabrica_lending_market
    loan-book.ts      # get_fabrica_loan_book (distribution of the loan records; no auction proceeds or per-loan liquidation rows)
    portfolio.ts      # get_land_portfolio
    protocol.ts       # get_fabrica_stats
    scoring.ts        # explain_property_checks
    borrowing.ts      # estimate_land_borrowing
    valuation.ts      # get_land_valuation (GraphQL GetValuation + REST /valuation/v1)
    activity.ts       # get_land_activity
    marketplace.ts    # get_land_order_book
    images.ts         # get_land_map_image, get_land_portfolio_map_image
    documents.ts      # get_land_trust_documents
    tax.ts            # get_land_tax_status (also the taxes line on get_land_property)
    knowledge.ts      # ask_fabrica
    parcels.ts        # find_us_parcel (Regrid type-ahead via the API, /go on-ramp link, per-client limit)
    coverage.ts       # check_county_coverage (static on-ramp rules table in src/data/onramp-coverage.json, built by scripts/build-coverage.mjs)
    support.ts        # contact_fabrica_support (help center link, support email, prefilled mailto; nothing sent)
    sign-requests.ts  # make_land_offer, list_land_for_sale, accept_land_offer, buy_land, cancel_land_order (prepare a sign request), get_sign_request
    loans.ts          # borrow_against_land, repay_loan_against_land (sign requests), get_loan_against_land (GetLoanContext, never cached)
    transactions.ts   # get_transaction_status (JSON-RPC reads only)
    account.ts        # get_my_account, get_my_properties (signed-in endpoint /mcp/account only, the connected user's own token)
    attention.ts      # what_needs_attention (signed-in endpoint only; ranks items from the other personal reads plus fees and checks on up to 20 live properties)
    my-loans.ts       # get_my_loans (signed-in endpoint only, portfolio:read; loans with live payoff, pool deposits valued at tick prices)
    offers.ts         # get_my_offers (signed-in endpoint only, portfolio:read; public order data for the account's wallets)
    onramps.ts        # get_my_properties_being_added, get_adding_status (signed-in endpoint only, onramp:read)
    own-wallet.ts     # On the signed-in endpoint, fills wallet arguments from the account (omitted or "me"; portfolio:read); public reads otherwise unchanged
    inputs.ts         # zod pieces shared by the tools' input schemas (property reference, image size)
  knowledge/
    index.ts          # typed, validated loader for generated/index.json (committed)
    search.ts         # BM25 retrieval with Fabrica synonyms and compound-term normalization
    facts.ts          # wording red lines the tests check the top passages against
    documents.ts      # whole documents reassembled from the index, for resources
  resources/
    knowledge.ts      # fabrica://docs, fabrica://help, fabrica://legal, fabrica://property/{tokenId}/trust-agreement, fabrica://network
  # scripts/build-knowledge.mjs builds the index; scripts/knowledge-diff.mjs and
  # .github/workflows/refresh-knowledge.yml open the daily refresh pull request
  clients/
    graphql.ts        # Fabrica GraphQL API client (primary data source)
    account.ts        # personal reads with the connected user's token (never cached, never on anonymous calls)
    rpc.ts            # Ethereum JSON-RPC reads (transaction, receipt, block number) for get_transaction_status
    generated/        # operations.ts: one result type per gql document, from scripts/codegen.mjs (committed; npm run codegen)
    subgraph.ts       # Lending pool subgraph client (dynamic pool discovery)
    cache.ts          # Short-TTL read cache with in-flight de-duplication (TtlCache)
    budgets.ts        # Read budgets (loan page budget, MAX_LOANS)
  data/
    us-counties.ts    # Regrid county paths to FIPS and name (copied from soil-app's /go table)
  sign-requests/
    store.ts          # SignRequestStore: Vercel KV / Upstash REST (or an in-process map locally), HMAC-checked records, 15-minute expiry
    http.ts           # GET /sign-requests/{id} and POST /sign-requests/{id}/result for the Soil sign page
  vercel-sign-requests.ts # Vercel function entry for /sign-requests
  well-known.ts       # /.well-known/mcp.json, /.well-known/mcp/server-card.json, /.well-known/ai-catalog.json (card read from a live in-process server)
  vercel-well-known.ts # Vercel function entry for /.well-known
  lifecycle.ts        # propertyStage(): unclaimed, being_added, replaced, live, removal_in_progress, removed, retired
  fees.ts             # fees assessed on a token, by currency address
  types/
    index.ts          # Names for the generated operation types (TokenListItem, TokenDetail, WalletModel...) plus the REST and subgraph shapes
  __tests__/          # vitest test suite