PatternFly MCP Server

A Model Context Protocol (MCP) server that provides access to PatternFly React development rules and documentation, built with Node.js and TypeScript.

What is MCP?

The Model Context Protocol (MCP) is an open standard that enables AI assistants to securely access external data sources and tools. This server provides a standardized way to expose PatternFly documentation and development rules to MCP-compatible clients.

Prerequisites

• Node.js 20.0.0 or higher
  • Note: Loading Tool Plugins from an external file or package requires Node.js >= 22 at runtime. On Node < 22, the server starts with built‑in tools only and logs a one‑time warning.
• NPM (or another Node package manager)

Installation

Local development

1. Install dependencies:

npm install

2. Build the project:

npm run build

3. Run in watch/dev mode (TypeScript via tsx):

npm run start:dev

Use via npx (after publishing)

npx @patternfly/patternfly-mcp

Or install locally in a project and run:

npm install @patternfly/patternfly-mcp
npx @patternfly/patternfly-mcp

Usage

The MCP server can communicate over stdio (default) or HTTP transport. It provides access to PatternFly documentation through built-in tools.

Built-in Tools

All tools accept an argument named urlList (array of strings) or componentName (string).

Tool: usePatternFlyDocs

Use this to fetch high-level index content (for example, a local README.md that contains relevant links, or llms.txt files in docs-host mode). From that content, you can select specific URLs to pass to fetchDocs.

• Parameters: urlList: string[] (required)

Tool: fetchDocs

Use this to fetch one or more specific documentation pages (e.g., concrete design guidelines or accessibility pages) after you’ve identified them via usePatternFlyDocs.

• Parameters: urlList: string[] (required)

Tool: componentSchemas

Use this to fetch the JSON Schema for a specific PatternFly component.

• Parameters: componentName: string (required)

Docs-host mode (local llms.txt mode)

If you run the server with --docs-host, local paths you pass in urlList are resolved relative to the llms-files folder at the repository root. This is useful when you have pre-curated llms.txt files locally.

Example:

npx @patternfly/patternfly-mcp --docs-host

Then, passing a local path such as react-core/6.0.0/llms.txt in urlList will load from llms-files/react-core/6.0.0/llms.txt.

MCP Client Configuration

Most MCP clients use a JSON configuration to specify how to start this server. Below are examples you can adapt to your MCP client.

Minimal client config (npx)

{
  "mcpServers": {
    "patternfly-docs": {
      "command": "npx",
      "args": ["-y", "@patternfly/patternfly-mcp@latest"],
      "description": "PatternFly React development rules and documentation"
    }
  }
}

HTTP transport mode

{
  "mcpServers": {
    "patternfly-docs": {
      "command": "npx",
      "args": ["-y", "@patternfly/patternfly-mcp@latest", "--http", "--port", "8080"],
      "description": "PatternFly docs (HTTP transport)"
    }
  }
}

Docs-host mode

{
  "mcpServers": {
    "patternfly-docs": {
      "command": "npx",
      "args": ["-y", "@patternfly/patternfly-mcp@latest", "--docs-host"],
      "description": "PatternFly docs (docs-host mode)"
    }
  }
}

Custom local tool

{
  "mcpServers": {
    "patternfly-docs": {
      "command": "npx",
      "args": [
        "-y",
        "@patternfly/patternfly-mcp@latest",
        "--tool",
        "./mcp-tools/local-custom-tool.js"
      ],
      "description": "PatternFly MCP with a local custom tool"
    }
  }
}

Features

HTTP Transport

By default, the server uses stdio. Use the --http flag to enable HTTP transport.

Options

• --http: Enable HTTP transport mode.
• --port <number>: Port to listen on (default: 8080).
• --host <string>: Host to bind to (default: 127.0.0.1).
• --allowed-origins <origins>: Comma-separated list of allowed CORS origins.
• --allowed-hosts <hosts>: Comma-separated list of allowed host headers.

DNS Rebinding Protection

This server enables DNS rebinding protection by default when running in HTTP mode. If you're behind a proxy or load balancer, ensure the client sends a correct Host header and configure --allowed-hosts accordingly.

Logging

The server uses a diagnostics_channel–based logger that keeps STDIO stdout pure by default. No terminal output occurs unless you enable a sink.

• --log-stderr: Enable terminal logging.
• --log-protocol: Forward logs to MCP clients (requires advertising capabilities.logging).
• --log-level <level>: Set log level (debug, info, warn, error). Default: info.
• --verbose: Shortcut for debug level.

Example:

npx @patternfly/patternfly-mcp --log-stderr --log-level debug

MCP Tool Plugins

You can extend the server's capabilities by loading Tool Plugins at startup. These plugins run out‑of‑process in an isolated Tools Host (Node.js >= 22) to ensure security and stability.

CLI Usage

• --tool <path|package>: Load one or more plugins. You can provide a path to a local file or the name of an installed NPM package.
  • Examples: --tool @acme/my-plugin, --tool ./local-plugins/weather-tool.js, --tool ./a.js,./b.js
• --plugin-isolation <none|strict>: Tools Host permission preset.
  • Default: strict. In strict mode, network and filesystem write access are denied; fs reads are allow‑listed to your project and resolved plugin directories.

Behavior and Limitations

• Node version gate: Node < 22 skips loading plugins from external sources with a warning; built‑ins still register.
• Supported inputs: ESM packages (installed in node_modules) and local ESM files with default exports.
• Not supported: Raw TypeScript sources (.ts) or remote http(s): URLs.

Troubleshooting

• If tool plugins don't appear, verify the Node version and check logs (enable --log-stderr).
• Startup load:ack warnings/errors from tool plugins are logged when stderr/protocol logging is enabled.
• If tools/call rejects with schema errors, ensure inputSchema is valid. See Authoring Tools for details.
• If the tool is having network access issues, you may need to configure --plugin-isolation none. This is generally discouraged for security reasons but may be necessary in some cases.

Terminology

• Tool: The low-level tuple format [name, schema, handler].
• Tool Config: The authoring object format { name, description, inputSchema, handler }.
• Tool Factory: A function wrapper (options) => Tool (internal).
• Tool Module: The programmatic result of createMcpTool, representing a collection of tools.

Authoring Tools

We recommend using the createMcpTool helper to define tools. It ensures your tools are properly normalized for the server.

Authoring a single Tool Module

import { createMcpTool } from '@patternfly/patternfly-mcp';

export default createMcpTool({
  name: 'hello',
  description: 'Say hello',
  inputSchema: {
    type: 'object',
    properties: { name: { type: 'string' } },
    required: ['name']
  },
  async handler({ name }) {
    return `Hello, ${name}!`;
  }
});

Authoring multiple tools in one module

import { createMcpTool } from '@patternfly/patternfly-mcp';

export default createMcpTool([
  { name: 'hi', description: 'Greets', inputSchema: {}, handler: () => 'hi' },
  { name: 'bye', description: 'Farewell', inputSchema: {}, handler: () => 'bye' }
]);

Input Schema Format

The inputSchema property accepts either plain JSON Schema objects or Zod schemas. Both formats are automatically converted to the format required by the MCP SDK.

JSON Schema (recommended):

inputSchema: {
  type: 'object',
  properties: {
    name: { type: 'string' },
    age: { type: 'number' }
  },
  required: ['name']
}

Zod Schema:

import { z } from 'zod';

inputSchema: {
  name: z.string(),
  age: z.number().optional()
}

Embedding the Server

You can embed the MCP server inside your application using the start() function and provide Tool Modules directly.

import { start, createMcpTool, type PfMcpInstance, type ToolModule } from '@patternfly/patternfly-mcp';

const echoTool: ToolModule = createMcpTool({
  name: 'echoAMessage',
  description: 'Echo back the provided user message.',
  inputSchema: {
    type: 'object',
    properties: { message: { type: 'string' } },
    required: ['message']
  },
  handler: async (args: { message: string }) => ({ text: `You said: ${args.message}` })
});

async function main() {
  const server: PfMcpInstance = await start({
    toolModules: [
      echoTool
    ]
  });

  // Optional: observe refined server logs in‑process
  server.onLog((event) => {
    if (event.level !== 'debug') {
      console.warn(`[${event.level}] ${event.msg || ''}`);
    }
  });

  // Graceful shutdown
  process.on('SIGINT', async () => {
    await server.stop();
    process.exit(0);
  });
}

main();

Development and Maintenance

Scripts

• npm run build: Build the project (cleans dist, type-checks, bundles).
• npm test: Run unit tests.
• npm run test:integration: Run e2e tests.
• npm run start:dev: Run with tsx in watch mode.
• npm run test:lint: Run ESLint.

Environment Variables

• DOC_MCP_FETCH_TIMEOUT_MS: Milliseconds to wait before aborting an HTTP fetch (default: 15000).

Inspector-CLI Examples

npx @modelcontextprotocol/inspector-cli \
  --config ./mcp-config.json \
  --server patternfly-docs \
  --cli \
  --method tools/call \
  --tool-name usePatternFlyDocs \
  --tool-arg urlList='["documentation/guidelines/README.md"]'

Resources

• Model Context Protocol
• PatternFly React
• MCP TypeScript SDK
• Node.js Documentation
• TypeScript Documentation