Appearance

Resources reference ​

Resources are the "read-only documents" surface of MCP. Where tools are actions an agent invokes, resources are artifacts an agent pulls for context. @dappql/mcp exposes four resource classes.

For the active-action surface, see tools. For why there are two surfaces, see MCP itself.

Listing ​

When the client calls resources/list, the server returns:

json
[
  {
    "uri": "dappql://project/AGENTS.md",
    "name": "Project AGENTS.md",
    "description": "The project-specific agent guide generated by dappql...",
    "mimeType": "text/markdown"
  },
  {
    "uri": "dappql://contracts/Token",
    "name": "Contract: Token",
    "description": "ABI and method summary for Token.",
    "mimeType": "application/json"
  },
  // ... one entry per contract
  {
    "uri": "dappql://project/config",
    "name": "dapp.config.js (summary)",
    "description": "Normalized view of the project config...",
    "mimeType": "application/json"
  },
  {
    "uri": "dappql://docs/library",
    "name": "DappQL library reference",
    "description": "Canonical reference for the DappQL toolchain...",
    "mimeType": "text/markdown"
  }
]

dappql://project/AGENTS.md only appears when AGENTS.md exists at your project root (i.e. after a dappql run with agentsFile enabled).

Reading ​

dappql://docs/library: canonical library reference ​

Returns the full DappQL library reference as markdown: React hooks, provider options, template vs singleton patterns, SDK factory syntax, non-React runtime, non-negotiables.

Bundled at build time, the @dappql/mcp package ships a copy of the monorepo's root AGENTS.md inside its assets/ directory. No network dependency; no drift against the installed version.

If the bundle is missing (corrupted install, etc.), the handler falls back to a pointer message directing the reader to the canonical URL on GitHub.

This is the resource agents should consult before writing or recommending any DappQL code. The projectInfo and listContracts tools emit hints pointing at it; the getDappqlReference tool is the active-call counterpart for agents that prefer tools over resources.

dappql://project/AGENTS.md: project-specific guide ​

Returns the project-tailored AGENTS.md generated by the dappql CLI at your project root. Same content (with your actual contracts) as the file on disk.

If you haven't run dappql yet, or set agentsFile: false in your config, this resource is absent from listResources, the handler throws if you try to read it directly.

Use this in addition to the library reference, not instead of. The project guide has your specific contract names and usage examples; the library reference has the generic API.

dappql://contracts/{Name}: per-contract summary + ABI ​

One resource per contract in your dap.config.js. Returns JSON:

json
{
  "name": "Token",
  "shape": "singleton",
  "address": "0x...",
  "reads": [
    { "name": "totalSupply", "stateMutability": "view", "inputs": [], "outputs": [{ "name": "", "type": "uint256" }] },
    { "name": "balanceOf", "stateMutability": "view", "inputs": [{ "name": "owner", "type": "address" }], "outputs": [...] }
  ],
  "writes": [...],
  "events": [
    { "name": "Transfer", "inputs": [{ "name": "from", "type": "address", "indexed": true }, ...] }
  ],
  "abi": [/* full ABI array */]
}

The abi field is always included in the resource read, unlike the getContract tool where it's opt-in via includeAbi: true.

Agents use these when they need full detail on a contract (all overloads, exact ABI types) beyond what listContracts surfaces.

dappql://project/config: normalized config view ​

A JSON summary of dap.config.js:

json
{
  "configPath": "/Users/you/myapp/dap.config.js",
  "root": "/Users/you/myapp",
  "chainId": 8453,
  "targetPath": "./src/contracts",
  "isSdk": true,
  "isModule": true,
  "contracts": ["Token", "ToDo", "UserWallet", ...]
}

Doesn't expose the mcp block (that lives in projectInfo along with the resolved policy) and doesn't expose ABIs (those are the per-contract resources).

Resources vs tools: practical guidance ​

  • Resources are loaded for context. Claude Code presents them in the "@" picker; agents may or may not auto-load them.
  • Tools are called on demand. Agents reach for tools far more readily than they browse resources.

The server offers both:

  • Resource dappql://docs/library, works when a client explicitly loads it.
  • Tool getDappqlReference, works unconditionally, every time the agent searches for dappql-related actions.

If you find an agent not reading the library reference when needed, its client may not be auto-loading resources. The tool route is the fallback that always works.