What is Fluent Mcp

Fluent MCP is a library that provides a chainable, fluent interface for building Model Context Protocol (MCP) servers with minimal code, similar to jQuery.

Use cases

Use cases include creating RESTful APIs, managing data for applications, and building backend services with minimal setup.

How to use

To use Fluent MCP, install it via npm and create an MCP server using the createMCP function. You can define resources and CRUD operations fluently.

Key features

Key features include a chainable API, built-in CRUD operations, resource management, flexible configuration, TypeScript support, and compatibility with JavaScript.

Where to use

Fluent MCP can be used in web applications, APIs, and any project that requires a structured way to manage resources and operations.

Fluent MCP

A chainable, fluent interface for building Model Context Protocol (MCP) servers and clients with minimal code. This library provides a jQuery-like API for creating MCP servers with built-in CRUD operations and resource management, as well as lightweight MCP clients for communicating with MCP servers.

Features

• Chainable API: Create and configure MCP servers and clients with a fluent, chainable interface
• Built-in CRUD Operations: Automatically generate CRUD tools for your resources
• Resource Management: Easily manage resources with built-in storage
• Client Support: Create MCP clients with the same familiar API
• Flexible Configuration: Simple by default, but customizable when needed
• TypeScript Support: Full TypeScript declarations for type safety
• JavaScript Compatibility: Works in both TypeScript and JavaScript environments

Installation

npm install @jasonkneen/fluent-mcp

Quick Start

# Run the demo server
npm start

Configuration Options

The createMCP function accepts an optional options parameter for customization:

import { createMCP } from '@jasonkneen/fluent-mcp';

// Simple usage with defaults
const simpleServer = createMCP('Notes API', '1.0.0');

// Advanced usage with custom options
const advancedServer = createMCP('Notes API', '1.0.0', {
  autoGenerateIds: false,     // Default: true - Set to false to manually manage IDs
  timestampEntries: false,    // Default: true - Set to false to disable automatic timestamps
  customOption: 'value'       // Any additional custom options
});

Available Options:

• autoGenerateIds (boolean, default: true): Automatically generate random IDs for CRUD operations
• timestampEntries (boolean, default: true): Automatically add createdAt/updatedAt timestamps
• Custom options: Any additional options you need for your specific use case

Using the Fluent MCP Server Interface

Simple Usage

There are multiple ways to use Zod with FluentMCP for schema validation:

Option 1: Import Zod separately (traditional approach)

import { createMCP, z } from '@jasonkneen/fluent-mcp';

// Create a new MCP server with fluent interface
const server = createMCP('Notes API', '1.0.0')
  // Define the Notes resource and CRUD operations
  .resource('Notes', {})
  .crud('Note', {
    title: z.string().describe('The title of the note'),
    content: z.string().describe('The content of the note'),
    tags: z.array(z.string()).optional().describe('Optional tags for the note')
  })

Option 2: Use the built-in .z property

import { createMCP } from '@jasonkneen/fluent-mcp';

// Create a new MCP server with fluent interface
const server = createMCP('Notes API', '1.0.0');

// Use the built-in .z property for schema validation
server
  .resource('Notes', {})
  .crud('Note', {
    title: server.z.string().describe('The title of the note'),
    content: server.z.string().describe('The content of the note'),
    tags: server.z.array(server.z.string()).optional().describe('Optional tags for the note')
  })

Option 3: Use the built-in .schema property (alternative name)

import { createMCP } from '@jasonkneen/fluent-mcp';

// Create a new MCP server with fluent interface
const server = createMCP('Notes API', '1.0.0');

// Use the built-in .schema property for schema validation
server
  .resource('Notes', {})
  .crud('Note', {
    title: server.schema.string().describe('The title of the note'),
    content: server.schema.string().describe('The content of the note'),
    tags: server.schema.array(server.schema.string()).optional().describe('Optional tags for the note')
  })

Option 4: Destructure for cleaner code

import { createMCP } from '@jasonkneen/fluent-mcp';

// Create a new MCP server with fluent interface
const server = createMCP('Notes API', '1.0.0');
const { z } = server;  // or const { schema } = server;

server
  .resource('Notes', {})
  .crud('Note', {
    title: z.string().describe('The title of the note'),
    content: z.string().describe('The content of the note'),
    tags: z.array(z.string()).optional().describe('Optional tags for the note')
  })
  
  // Add a custom search tool
  .tool(
    'searchNotes',
    {
      query: z.string().describe('The search query')
    },
    async ({ query }) => {
      // Implementation...
    }
  )
  
  // Enable stdio transport and start the server
  .stdio()
  .start();

Advanced Usage

import { createMCP, z } from '@jasonkneen/fluent-mcp';

// Create a new MCP server with advanced options
const server = createMCP('Task Manager API', '1.0.0', {
  autoGenerateIds: false,  // We'll manage IDs ourselves
  timestampEntries: false  // No automatic timestamps
})
  // Define resources with custom options
  .resource('Tasks', {})
  .crud('Task', {
    id: z.string().describe('The unique ID of the task'),
    title: z.string().describe('The title of the task'),
    // ...more fields
  }, {
    singularName: 'Task',
    pluralName: 'Tasks'  // Explicit pluralization
  })
  
  // Start the server
  .start();

Using the Fluent MCP Client Interface

Simple Usage

import { createMCPClient } from '@jasonkneen/fluent-mcp';

// Create an MCP client with fluent API
const client = createMCPClient('Notes Client', '1.0.0')
  // Configure connection to an MCP server over stdio
  .stdio('node', ['path/to/server.js'])
  // Connect to the server
  .connect();
  
// Call server tools
const result = await client.callTool('searchNotes', { query: 'example' });
console.log(client.parseToolResult(result)); // Parse JSON response

HTTP Client

import { createMCPClient } from '@jasonkneen/fluent-mcp';

// Create an HTTP client
const client = createMCPClient('Notes HTTP Client', '1.0.0')
  // Configure HTTP connection
  .http('http://localhost:3000/mcp')
  // Connect to the server
  .connect();

// List available tools
const tools = await client.listTools();
console.log(tools);

// Disconnect when done
await client.disconnect();

Advanced Client Usage

import { createMCPClient, LoggingMessageNotificationSchema } from '@jasonkneen/fluent-mcp';

// Create a client with notification handlers
const client = createMCPClient('Notes Client', '1.0.0')
  // Register notification handler
  .onNotification(LoggingMessageNotificationSchema, (notification) => {
    console.log(`Server notification: ${notification.params.level} - ${notification.params.data}`);
  })
  // Register error handler
  .onError((error) => {
    console.error('Client error:', error);
  })
  // Configure connection
  .stdio('node', ['path/to/server.js']);

// Connect and use the client
await client.connect();

// Use helper methods
const resources = await client.listResources();
const prompts = await client.listPrompts();
const promptTemplate = await client.getPrompt('examplePrompt', { param: 'value' });

// Disconnect when done
await client.disconnect();

Running the Demos

Server Demos

npm start            # Run the JavaScript demo server
# or
npm run demo         # Same as above
npm run demo:ts      # Run the TypeScript demo server

Client Demos

npm run demo:client       # Run the stdio client demo
npm run demo:http-client  # Run the HTTP client demo

Available Methods

Core Methods

• createMCP(name, version, options): Create a new FluentMCP server instance with flexible configuration options
• createMCPClient(name, version, options): Create a new FluentMCPClient instance with flexible configuration options
• connectMCPClient(name, version, transportConfig): Create and connect a client in one step
• z: Re-exported Zod library for schema definitions (no need to install Zod separately)

Server Methods

• resource(name, initialData): Initialize a resource store
• getResource(name): Get a resource store
• setResource(name, id, data): Set a resource value
• deleteResource(name, id): Delete a resource value
• crud(resourceName, schema, options): Create CRUD operations for a resource
• tool(name, schema, handler): Add a tool to the server
• stdio(): Enable stdio transport
• start(): Start the server with the configured transport

Client Methods

• onError(handler): Register an error handler
• onNotification(schema, handler): Register a notification handler
• stdio(command, args, options): Configure stdio transport
• http(url, options): Configure HTTP transport
• callTool(name, args, resultSchema): Call a tool on the MCP server
• listTools(): List available tools on the server
• listResources(): List available resources on the server
• listPrompts(): List available prompts on the server
• getPrompt(name, args): Get a prompt from the server
• parseToolResult(result): Parse a tool result into JSON
• connect(): Connect to the MCP server
• disconnect(): Disconnect from the MCP server

Testing

Run the tests with:

npm test

Or watch mode:

npm run test:watch

Customizing

You can extend the FluentMCP class with your own methods to add additional functionality. The chainable design makes it easy to add new capabilities while maintaining a clean API.