feat: add @evolution-sdk/mcp — Model Context Protocol server with 66 tools#207
Open
FractionEstate wants to merge 11 commits intoIntersectMBO:mainfrom
Open
feat: add @evolution-sdk/mcp — Model Context Protocol server with 66 tools#207FractionEstate wants to merge 11 commits intoIntersectMBO:mainfrom
FractionEstate wants to merge 11 commits intoIntersectMBO:mainfrom
Conversation
- Implemented session management with ClientSession, BuilderSession, ResultSession, SubmitSession, and ClusterSession types. - Created SessionStore class for managing session records, including methods for creating, retrieving, updating, and deleting sessions. - Added comprehensive tests for the HTTP server, covering various tools and functionalities, including client creation, transaction building, encoding/decoding, and more. - Introduced TypeScript configuration files for building and testing, ensuring proper type checking and output management. - Configured Vitest for testing with appropriate timeouts and exclusions.
- Implement tests for address building (enterprise, base, reward) - Add tests for metadata tools (build, parse, buildAuxiliaryData) - Include credential tools tests (makeKeyHash, makeScriptHash, fromCbor) - Introduce DRep tools tests (fromKeyHash, fromBech32, alwaysAbstain, alwaysNoConfidence) - Add value tools tests (onlyCoin, add, geq, getAda, isAdaOnly) - Implement assets tools tests (fromRecord, lovelaceOf, getUnits, hasMultiAsset, merge, fromCbor) - Include unit tools tests (fromUnit, toLabel, fromLabel) - Add coin tools tests (add, subtract, compare, validate, maxCoinValue) - Implement network tools tests (toId, fromId, validate) - Add data construction tools tests (int, bytes, constr, list, match, isInt, isConstr) - Include hash tools test (hashTransactionRaw) - Verify all tools are listed in the client
- Implement tests for mint_tools including singleton, insert, getByHex, and policyCount actions. - Add tests for withdrawals_tools covering singleton, size, entries, and isEmpty actions. - Introduce tests for anchor_tools, certificate_tools, redeemer_tools, voting_tools, script_ref_tools, governance_action_tools, proposal_tools, tx_output_tools, and plutus_data_codec_tools. - Ensure all tools are verified to be listed in the client.
…tificates, constitution, and protocol parameter updates
…ver functionality - Implemented tests for transaction input, body, pointer address, plutus value, script, BIP32 key, and signature tools. - Added documentation for the MCP server, detailing installation, usage, tool categories, and example interactions.
Contributor
There was a problem hiding this comment.
Pull request overview
This PR adds @evolution-sdk/mcp, an HTTP-based Model Context Protocol server that exposes 81 callable tools from the Evolution SDK for AI agents. It includes the server implementation, session management, configuration, a postinstall bootstrap script, comprehensive tests, and documentation.
Changes:
- New
packages/evolution-mcp/package with MCP server, HTTP entrypoint, session management, codec helpers, and a Linux-first postinstall auto-start script - Documentation page (
docs/content/docs/mcp/index.mdx) and sidebar navigation update for MCP server usage - Updated root
README.mdwith MCP package in architecture tree and package table
Reviewed changes
Copilot reviewed 17 out of 19 changed files in this pull request and generated 4 comments.
Show a summary per file
| File | Description |
|---|---|
packages/evolution-mcp/package.json |
Package manifest with dependencies, scripts, and exports |
packages/evolution-mcp/src/server.ts |
MCP server with 81 tool registrations (not in diff, referenced) |
packages/evolution-mcp/src/http.ts |
HTTP server setup with health and MCP endpoints |
packages/evolution-mcp/src/config.ts |
Environment-based configuration resolution |
packages/evolution-mcp/src/codec.ts |
CBOR codec helpers for assets, addresses, UTxOs, transactions |
packages/evolution-mcp/src/sessions.ts |
Stateful session management for clients, builders, results |
packages/evolution-mcp/src/bin.ts |
CLI entrypoint for serving the MCP server |
packages/evolution-mcp/src/index.ts |
Public API barrel export |
packages/evolution-mcp/scripts/postinstall.mjs |
Linux-first auto-start bootstrap script |
packages/evolution-mcp/test/server.test.ts |
Comprehensive integration test (2200+ lines) |
packages/evolution-mcp/README.md |
Package documentation |
docs/content/docs/mcp/index.mdx |
Documentation page for MCP server |
docs/content/docs/meta.json |
Sidebar navigation update |
README.md |
Root README updated with MCP references |
pnpm-lock.yaml |
Lock file updated with new dependencies |
packages/evolution-mcp/tsconfig*.json |
TypeScript configuration files |
packages/evolution-mcp/vitest.config.ts |
Vitest test configuration |
Files not reviewed (1)
- pnpm-lock.yaml: Language not supported
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
You can also share your feedback on Copilot code review. Take the survey.
Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>
- Add StdioServerTransport via 'evolution-mcp stdio' command - Export startStdioServer from package index - Update bin.ts with stdio command and updated usage text - Update package README and docs page with stdio configuration
- Remove 207 z.describe() calls from parameter schemas (~10K chars saved) - Trim all tool descriptions to ≤60 chars (~3.2K chars saved) - Consolidate 9 devnet tools into 1 with action enum (81→73 tools) - Reuse single McpServer instance across HTTP requests - Add request queue to serialize concurrent MCP requests - Update tests for devnet tool consolidation
…onBody, TransactionMetadatum, TransactionWitnessSet, and SDK builders - Added PlutusData schema and interface to TSchema documentation. - Expanded Transaction documentation with encoding and parsing sections, including new methods for handling CBOR bytes and hex. - Updated TransactionBody documentation to include new methods for CBOR conversion with format. - Introduced equality check for TransactionMetadatum in the documentation. - Enhanced TransactionWitnessSet documentation with new methods for CBOR conversion with format. - Updated SDK builders documentation to reflect changes in transaction fee calculations and deprecated options. - Added measure-tools script for analyzing tool sizes in the evolution MCP.
Merge related tools to cut tools/list payload from 57,914 to 54,937 bytes (~13.7K tokens): - client_attach_provider + client_attach_wallet → client_attach (type discriminator) - sign_result_call + submit_builder_call → result_call (handle-based dispatch) - transaction_codec + witness_set_codec + script_codec → absorbed into typed_export_codec - bech32_codec + bytes_codec → encoding_codec (prefixed actions) - cip68_codec tokenLabels → absorbed into plutus_data_codec_tools - Add hasSubmit() to session store for result_call routing - Update tests for all renamed/merged tools - Delete temporary measure-tools.ts
FractionEstate
changed the title
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Adds
@evolution-sdk/mcp, an HTTP-based Model Context Protocol server that exposes the full Evolution SDK surface as 66 callable tools for AI agents (GitHub Copilot, Claude, Cursor, and any MCP-compatible client).The server starts automatically via
postinstalland listens athttp://localhost:10000/mcp.What's Included
New Package:
packages/evolution-mcp/src/server.tssrc/bin.tssrc/http.tssrc/config.tssrc/codec.tssrc/sessions.tssrc/index.tsscripts/postinstall.mjstest/server.test.tsTool Categories (66 tools)
Documentation
docs/content/docs/mcp/index.mdxwith installation, tool categories, MCP client configuration (Claude, VS Code, Cursor), and usage examplesdocs/content/docs/meta.jsonto add MCP to sidebar navigationREADME.mdwith MCP in architecture tree, package table, and core modules sectionToken Optimization
Tools have been consolidated from an initial 81 down to 66 to reduce the
tools/listpayload size that LLM clients must process:Key consolidations:
client_attach_provider+client_attach_wallet→client_attach(type discriminator)sign_result_call+submit_builder_call→result_call(handle-based dispatch)transaction_codec+witness_set_codec+script_codec→ absorbed intotyped_export_codecbech32_codec+bytes_codec→encoding_codec(prefixed actions)cip68_codectokenLabels → absorbed intoplutus_data_codec_toolsdevnettool with action discriminatorz.describe()annotations removed (Zod v4 schema descriptions used instead)Package Coverage
Covers all four workspace packages:
@evolution-sdk/evolution— core SDK@evolution-sdk/aiken-uplc— Aiken UPLC evaluator@evolution-sdk/scalus-uplc— Scalus UPLC evaluator@evolution-sdk/devnet— local development networkConfiguration
EVOLUTION_MCP_HOST127.0.0.1EVOLUTION_MCP_PORT10000EVOLUTION_MCP_PATH/mcpEVOLUTION_MCP_HEALTH_PATH/healthEVOLUTION_MCP_SKIP_POSTINSTALLTesting
pnpm --filter @evolution-sdk/mcp build pnpm --filter @evolution-sdk/mcp testAll tests pass. Build is clean with no TypeScript errors.