genskill-mcp

An MCP server that lets any AI agent build on GenLayer: search the docs, inspect contracts and transactions over RPC, and scaffold, lint, and test Intelligent Contracts.

genskill-mcp is a Model Context Protocol server for MCP-compatible clients (Claude Code, Cursor, VS Code, Gemini CLI, Codex, and remote MCP clients over HTTP). It combines searchable GenLayer documentation, live protocol/RPC inspection of contracts and transactions, and a contract authoring toolkit (scaffold, lint, and test Intelligent Contracts), so an agent can go from zero to a deployable contract without leaving its editor.

This project does not sign transactions or manage private keys. It supports live node inspection and contract interaction through GenLayer JSON-RPC methods such as gen_call, gen_getContractState, gen_getContractCode, gen_getContractSchema, gen_getTransactionStatus, and gen_getTransactionReceipt.

Install

Per-client setup (Claude Code, Cursor, VS Code, Gemini, Codex, remote) is in the quickstarts below.

What this server does

The server loads the official GenLayer docs bundle:

• https://docs.genlayer.com/full-documentation.txt

It parses that bundle into sections and exposes:

• searchable MCP tools
• a browsable docs index resource
• individual section resources
• live GenLayer JSON-RPC tools for contract and transaction inspection
• a browsable RPC configuration resource
• contract authoring tools: scaffold a starter contract and lint it before deploy
• guided MCP prompts for writing, testing, and debugging contracts

This repository supports two transports:

• stdio for local CLI tools such as Claude Code, Codex, Cursor, VS Code, and Gemini CLI
• Streamable HTTP for deployed remote MCP usage

Build a contract (authoring tools, new in 2.2)

If you are new to GenLayer, this is the fast path from zero to a deployable contract. It does not just point you at docs, it gives you working code and checks it.

• `genlayer_scaffold_contract` generates a working starter Intelligent

Contract for a template (storage, llm-judge, web-oracle, token). The output already has the runner header pinned and avoids the common GenVM deploy-killers, so it deploys as-is.

• `genlayer_lint_contract` runs static pre-deploy checks on contract source.

It catches the mistakes that make a deploy finalize with a bare invalid_contract (no stack trace): a comment line directly under the runner header, an unpinned or :test / :latest runner, a missing gl.Contract class, forbidden sandbox imports (os, sys, subprocess, random, ...), and GenVM Python-subset issues such as for loops, sorted, .sort, lambda, and list / dict storage fields.

• `genlayer_scaffold_test` generates a fast direct-mode test

(genlayer-test) for a template, using the real fixtures (direct_vm, direct_deploy, direct_alice) and mocking web/LLM calls so tests stay deterministic.

Three guided prompts wrap the workflow for any MCP client:

• `genlayer_write_contract` scaffold, decide what needs consensus, then lint.
• `genlayer_test_contract` direct-mode then integration testing.
• `genlayer_debug_deploy` the checklist for a deploy that errored on-chain.

And a single always-available resource, `genlayer://guide/contract-rules`, is an authoritative cheat sheet (skeleton, storage types, web/LLM/equivalence APIs, the GenVM Python-subset rules, and the deploy/finalize/debug checklist) that any connecting agent can read to get contract writing and debugging right. It tracks the latest GenLayer docs and the official write-contract / direct-tests skills.

Typical loop: scaffold, edit, genlayer_lint_contract until it is clean, deploy, then inspect it live with genlayer_get_contract_snapshot.

RPC configuration

Live protocol tools use the configured GenLayer RPC endpoint.

• GENLAYER_RPC_URL: JSON-RPC endpoint to use
• GENLAYER_RPC_TIMEOUT_MS: timeout for live RPC requests

If GENLAYER_RPC_URL is not set, the server defaults to:

https://studio.genlayer.com/api

Quickstart for Claude Code

claude mcp add --transport stdio genskill -- npx -y genskill-mcp

Then start Claude Code:

claude

Inside Claude Code, run:

/mcp

The genskill server and its tool endpoints should be listed.

Quickstart for Cursor (per-project)

Add this to .cursor/mcp.json:

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

[!TIP] If a Cursor version does not recognize mcpServers, use mcp_servers as the top-level key instead.

Quickstart for VS Code (per-workspace)

Add this to .vscode/mcp.json:

{
  "servers": {
    "genskill": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "genskill-mcp"]
    }
  },
  "inputs": []
}

Quickstart for Gemini CLI

Add the MCP server globally:

gemini mcp add --scope user genskill npx -y genskill-mcp

Confirm it is registered:

gemini mcp list

Quickstart for Codex

Add the MCP server with the Codex CLI:

codex mcp add genskill -- npx -y genskill-mcp

Confirm it is registered:

codex mcp list

Alternatively, add this to a Codex MCP config:

[mcp_servers.genskill]
command = "npx"
args = ["-y", "genskill-mcp"]

Restart Codex if needed so it reloads the MCP config.

Quickstart from source

For source-based usage instead of installing from npm:

1. Clone the repo:

   git clone https://github.com/Jr-kenny/genskill-mcp
   cd genskill-mcp

1. Install dependencies and build:

   npm install
   npm run build

1. Run the local entrypoint:

   node /absolute/path/to/genskill-mcp/dist/cli.js

Substitute that node .../dist/cli.js command in any MCP client config for source-based usage over npx.

Quickstart for remote MCP clients

For remote MCP clients, run the HTTP entrypoint and deploy it as a public web service.

This is not Claude-specific. It is the deployed transport for any client that can connect to remote MCP servers over Streamable HTTP, including chat-style AI apps where that capability is available.

1. Deploy this repository to Vercel.

1. The deployed MCP endpoint is:

   https://genskill-mcp.vercel.app/mcp

1. The deployed service also exposes:

• GET / for a small server info response
• GET /health for health checks
• POST /mcp for MCP Streamable HTTP requests

1. Add the deployed MCP URL in a remote MCP client as an HTTP MCP server.

Use:

https://genskill-mcp.vercel.app/mcp

This applies to Claude-hosted integrations, ChatGPT-style apps, and other remote AI clients where MCP server URLs are supported.

For local HTTP testing, run:

   npm install
   npm run build
   npm run start:http

It listens on port 3000 by default. Set the PORT environment variable to change it.

Vercel deployment

This repository is configured for Vercel through vercel.json and the Web-standard API functions in api/.

Public MCP endpoint on Vercel:

https://genskill-mcp.vercel.app/mcp

Useful checks:

• https://genskill-mcp.vercel.app/
• https://genskill-mcp.vercel.app/health
• POST https://genskill-mcp.vercel.app/mcp from an MCP client

Notes:

• /mcp is routed to the Vercel function at /api/mcp.mjs.
• The Vercel endpoint uses the MCP SDK Web-standard Streamable HTTP transport in stateless mode.
• POST requests return JSON responses where possible, which is friendlier for serverless hosting than holding long SSE streams open.
• If the docs update while the service is already deployed, call genlayer_refresh_docs from an MCP client or redeploy the project.

Tool endpoints

High-level orchestration tools now use a canonical machine-readable response shape with:

• kind
• summary
• current_state
• blockers
• next_actions
• fallbacks
• data

The autopilot and capability surfaces are capability-aware: they should prefer only actions supported by the currently configured endpoint and explicitly downgrade unsupported debug or ops paths into fallbacks.

Live protocol tools

1. genlayer_list_networks

Lists documented GenLayer network presets, chain IDs, and RPC URLs.

1. genlayer_start_workflow_session

Creates a persisted workflow session from a generated contract workflow plan.

1. genlayer_list_workflow_sessions

Lists persisted workflow sessions ordered by most recently updated.

1. genlayer_get_workflow_session

Reads a persisted workflow session by id.

1. genlayer_update_workflow_step

Marks a workflow session step as completed or pending.

1. genlayer_autopilot_brief

Generates a single operator-grade brief with endpoint capabilities, contract context, workflow plans, handoff steps, and relevant docs.

1. genlayer_load_contract_artifact

Loads a local contract artifact or bytecode file and returns base64 plus file metadata.

1. genlayer_probe_endpoint_capabilities

Probes which HTTP and RPC surfaces are actually exposed on the configured GenLayer deployment.

1. genlayer_generate_agent_handoff

Generates an explicit ordered handoff bundle so weaker agents know exactly which genskill-mcp tools to call next.

1. genlayer_get_contract_interface

Normalizes a contract schema into constructor, view methods, and write methods.

1. genlayer_plan_contract_action

Builds a schema-validated execution plan for deploy, read, or write actions.

1. genlayer_plan_contract_workflow

Builds a multi-phase contract workflow covering deploy, wait, snapshot, interaction, and diagnosis.

1. genlayer_run_transaction_report

Orchestrates waiting, inspection, status explanation, optional trace lookup, and optional contract snapshot into one report.

1. genlayer_run_contract_report

Orchestrates network context, contract snapshot, interface, workflow, and default plans into one report.

1. genlayer_generate_typescript_workflow

Generates GenLayerJS deploy/read/write snippets from a contract schema or deployed contract.

1. genlayer_generate_contract_playbook

Generates a schema-aware deployment and interaction playbook for a contract.

1. genlayer_node_health

Calls the configured GenLayer node HTTP GET /health endpoint.

1. genlayer_network_status

Returns a combined live snapshot of node health, chain id, block height, sync status, and optional debug ping status.

1. genlayer_balance

Calls the configured GenLayer HTTP GET /balance endpoint for the node operator.

1. genlayer_eth_get_balance

Calls eth_getBalance through the configured GenLayer RPC endpoint.

1. genlayer_raw_rpc

Calls gen_*, eth_*, zks_*, or zksync_* methods directly against the configured endpoint.

1. genlayer_trace_transaction

Calls gen_dbg_traceTransaction when the target node exposes debug methods.

1. genlayer_metrics

Fetches Prometheus-style metrics from the configured HTTP GET /metrics endpoint.

1. genlayer_submit_raw_transaction

Submits a signed raw transaction through eth_sendRawTransaction.

1. genlayer_inspect_transaction

Combines gen_getTransactionStatus, gen_getTransactionReceipt, and eth_getTransactionByHash into one response.

1. genlayer_wait_for_transaction

Polls transaction status until accepted or finalized.

1. genlayer_explain_transaction_status

Interprets transaction status into finality phase, appealability, and next-step guidance.

1. genlayer_call_contract

Executes gen_call for read, write-simulation, or deploy-simulation requests.

1. genlayer_get_contract_schema

Calls gen_getContractSchema for base64-encoded contract code.

1. genlayer_get_contract_state

Calls gen_getContractState for a deployed contract.

1. genlayer_get_contract_code

Calls gen_getContractCode for a deployed contract.

1. genlayer_get_contract_snapshot

Fetches state, deployed code, and derived schema in one call.

1. genlayer_get_transaction_status

Calls gen_getTransactionStatus for lightweight transaction polling.

1. genlayer_get_transaction_receipt

Calls gen_getTransactionReceipt for full processed transaction data.

1. genlayer_syncing

Calls gen_syncing on the configured endpoint.

Documentation tools

1. genlayer_search_docs

Searches the documentation bundle and returns ranked matches with snippets.

1. genlayer_refresh_docs

Force-refreshes the cached GenLayer documentation bundle from the configured source. Use this after the GenLayer team ships new docs, for example new Studio GEN, payable contract, Faucet, Tip Jar, or MetaMask updates.

1. genlayer_read_doc

Reads a section by slug, path, title, or fuzzy query.

1. genlayer_get_doc_by_slug

Reads a section by exact slug, path, docs URL, or resource URI.

1. genlayer_search_examples

Searches example-heavy sections that contain commands, code blocks, SDK snippets, or config examples.

1. genlayer_get_related_docs

Finds related documentation pages based on section path, title, and neighborhood in the docs tree.

1. genlayer_list_topics

Lists top-level GenLayer documentation topics with counts and example pages.

1. genlayer_list_sections

Lists available parsed documentation sections.

Resources

1. genlayer://protocol/networks

Documented GenLayer network presets, RPC URLs, and chain IDs.

1. genlayer://workflow/sessions

List of persisted workflow sessions.

1. genlayer://workflow/session/{id}

Persisted workflow session with step completion state.

1. genlayer://workflow/autopilot

Single operator-grade brief for the configured endpoint and current contract context.

1. genlayer://protocol/rpc-config

JSON document showing the configured RPC endpoint, timeout, and supported helper methods.

1. genlayer://protocol/capabilities

Probed endpoint capabilities showing which HTTP and RPC surfaces are actually exposed.

1. genlayer://protocol/transaction/{txId}

Combined transaction inspection resource for a specific transaction hash.

1. genlayer://protocol/transaction/{txId}/report

Composed transaction report with status interpretation and optional trace data when exposed.

1. genlayer://protocol/contract/{address}/state

Current accepted-state snapshot for a specific deployed contract.

1. genlayer://protocol/contract/{address}/snapshot

Combined state, code, and schema snapshot for a specific deployed contract.

1. genlayer://protocol/contract/{address}/playbook

Schema-aware deployment and interaction playbook for a deployed contract.

1. genlayer://protocol/contract/{address}/report

Composed contract report with network context, snapshot, interface, workflow, and default plans.

1. genlayer://protocol/contract/{address}/plans

Default workflow plus default read/write action plans for a deployed contract.

1. genlayer://protocol/contract/{address}/method/{method}/plan/{action}

Default schema-validated plan for a specific read or write method.

1. genlayer://docs/index

JSON index of all parsed sections.

1. genlayer://docs/section/{slug}

Individual documentation sections as read-only resources.

Project structure

How it's built

This MCP server is a lightweight TypeScript implementation built on the official MCP SDK.

Core components

• Built on @modelcontextprotocol/sdk
• Uses StdioServerTransport for local MCP clients
• Uses zod to validate tool arguments
• Fetches the GenLayer docs bundle from the official docs site
• Parses the bundle into section-level resources based on each # path/to/file.mdx boundary
• Uses a simple deterministic ranking function over titles, slugs, paths, and body text

Configuration

Optional environment variables:

• GENLAYER_DOCS_URL: alternate source URL or local file path for the docs bundle
• GENLAYER_DOCS_CACHE_FILE: cache location for the downloaded bundle
• GENLAYER_DOCS_REFRESH_HOURS: cache freshness window in hours, default 24
• GENLAYER_DOCS_TIMEOUT_MS: HTTP timeout in milliseconds, default 15000

The server also refreshes stale in-memory snapshots automatically. For long-running HTTP deployments, call genlayer_refresh_docs when the GenLayer team ships new documentation and an immediate update is needed without restarting the service.

Local development

This section is only for working on the MCP server itself.

npm install
npm run build
npm run check
npm start

npm run check verifies that the server can fetch and parse the live GenLayer docs bundle.

Releasing (maintainers)

Releases are published to npm automatically by .github/workflows/release.yml when a v* tag is pushed. One-time setup: add an npm automation token as the NPM_TOKEN repository secret (gh secret set NPM_TOKEN).

To cut a release:

npm version minor        # bumps package.json, commits, creates the tag vX.Y.Z
git push --follow-tags   # pushes the commit + tag; CI builds, tests, publishes

The workflow checks the tag matches package.json, runs the tests, and publishes with npm provenance. Once published, consumers update with:

npx -y genskill-mcp@latest      # always newest
npm update -g genskill-mcp      # if installed globally

Remote (Vercel) users need no action — the hosted endpoint auto-deploys from main; clients pick up changes on reconnect.

Credits

Built and maintained by:

• Jr-kenny
• Prime isles