Skip to content
EvolveEvolveEvolve

mcp-core

@evolve-framework/mcp-core · v2.0.0 snapshot (d1e8659)

The building blocks for an MCP (Model Context Protocol) server that exposes a storefront's GraphQL operations as tools for AI assistants, over HTTP or stdio, with customers signing in through OAuth on the storefront's own login page.

When to use

Use it to build an MCP service next to your storefront API, so an assistant can search products or manage a cart through the same gateway the storefront uses. Its codegen turns the GraphQL operations you mark with @mcpTool into tools, and its plugins add prompts and resources. With OAuth, a customer adds the service's URL to their assistant, signs in on the storefront, and the assistant acts for them, with the scopes they approved. A project without an AI assistant integration does not need it.

Get started

  1. Install the package with the peer dependencies it needs. It comes from the Evolve registry, which needs a one-time sign-in.

    pnpm add @evolve-framework/mcp-core @evolve-framework/core @opentelemetry/api fastify graphql
    Requirements5
    @evolve-framework/core>= 1.0.0 < 2.0.0
    @opentelemetry/api^1.9.0
    @types/node>=22optional
    fastify>= 5.12.1 < 6.0.0
    graphql>= 16.0.0 < 17.0.0

For example:

import { createApplication } from "@evolve-framework/core";
import { MCPCoreConfig } from "@evolve-framework/mcp-core";
import { createMcpModule } from "@evolve-framework/mcp-core/application";


class Config extends MCPCoreConfig {
  override readonly COMPONENT_NAME = "mcp-customer";
  override readonly HTTP_PORT = 4100;
}


const config = new Config();
await config.load();


// In a variable, so a checkout that has not run codegen still typechecks.
const generatedTools = "./generated/mcp-tools.generated.ts";


const app = await createApplication({
  name: config.COMPONENT_NAME,
  module: await createMcpModule({
    config,
    name: "mcp-customer",
    loadTools: () => import(generatedTools),
    oauth: { resourceName: "Shop tools" },
  }),
  http: { address: { host: config.HTTP_HOST, port: config.HTTP_PORT } },
});


await app.start();

Configuration

MCPCoreConfig reads 21 environment variables. See which

Entry points

@evolve-framework/mcp-coreThe MCP server: tool, prompt and resource registration, the GraphQL client the tools call, the OAuth authorization server, JWT validation and token refresh.55 exports
@evolve-framework/mcp-core/codegenThe codegen plugins and transforms that generate tools from operations, plus persisted-document validation.8 exports
@evolve-framework/mcp-core/codegen/toolsThe codegen plugin that generates the tool definitions.2 exports
@evolve-framework/mcp-core/codegen/persisted-queriesThe persisted-documents transform that keeps the tool operations registered with the gateway.2 exports
@evolve-framework/mcp-core/codegen/validate-persisted-documentsA check that every tool's operation is registered with the gateway.4 exports
@evolve-framework/mcp-core/pluginsThe plugin interface for adding tools, prompts and resources.2 exports
@evolve-framework/mcp-core/applicationcreateMcpModule, a service as an application module with OAuth when given oauth, and startMcpStdio, the same service over stdio.4 exports