LiteMCP

A TypeScript framework for building MCP (Model Context Protocol) servers elegantly

Features

• Simple Tool, Resource, Prompt definition
• Full TypeScript support
• Built-in logging
• Built-in error handling
• Built-in CLI for testing and debugging
• Built-in support for SSE transport

Installation

bash
npm install litemcp zod

Quickstart

js
import { LiteMCP } from "litemcp";
import { z } from "zod";

const server = new LiteMCP("demo", "1.0.0");

server.addTool({
  name: "add",
  description: "Add two numbers",
  parameters: z.object({
    a: z.number(),
    b: z.number(),
  }),
  execute: async (args) => {
    return args.a + args.b;
  },
});

server.addResource({
  uri: "file:///logs/app.log",
  name: "Application Logs",
  mimeType: "text/plain",
  async load() {
    return {
      text: "Example log content",
    };
  },
});

server.start();

You can test the server in terminal with:

bash
npx litemcp dev server.js

Core Concepts

Tools

Tools in MCP allow servers to expose executable functions that can be invoked by clients and used by LLMs to perform actions.

js
server.addTool({
  name: "fetch",
  description: "Fetch the content of a url",
  parameters: z.object({
    url: z.string(),
  }),
  execute: async (args) => {
    const content = await fetchWebpageContent(args.url);
    return content;
  },
});

Resources

Resources represent any kind of data that an MCP server wants to make available to clients. This can include:

• File contents
• Screenshots and images
• Log files
• And more

Each resource is identified by a unique URI and can contain either text or binary data.

js
server.addResource({
  uri: "file:///logs/app.log",
  name: "Application Logs",
  mimeType: "text/plain",
  async load() {
    return {
      text: await readLogFile(),
    };
  },
});

You can also return binary contents in load:

js
async load() {
  return {
    blob: 'base64-encoded-data'
  }
}

Prompts

Prompts enable servers to define reusable prompt templates and workflows that clients can easily surface to users and LLMs. They provide a powerful way to standardize and share common LLM interactions.

js
server.addPrompt({
  name: "git-commit",
  description: "Generate a Git commit message",
  arguments: [
    {
      name: "changes",
      description: "Git diff or description of changes",
      required: true,
    },
  ],
  load: async (args) => {
    return `Generate a concise but descriptive commit message for these changes:\n\n${args.changes}`;
  },
});

Logging

You can send log messages to the client with server.logger

js
server.addTool({
  name: "download",
  description: "Download a file from a url",
  parameters: z.object({
    url: z.string(),
  }),
  execute: async (args) => {
    server.logger.info("Downloading file", { url: args.url });
    // ...
    server.logger.info("Downloaded file", { url: args.url });
    return response;
  },
});

The logger object has the following methods:

• debug(message: string, context?: JsonValue)
• info(message: string, context?: JsonValue)
• warn(message: string, context?: JsonValue)
• error(message: string, context?: JsonValue)

Running Your Server

Debugging with mcp-cli

The fastest way to test and debug your server is with mcp-cli:

bash
npx litemcp dev server.js
npx litemcp dev server.ts // ts files are also supported

This will run your server with mcp-cli for testing and debugging your MCP server in the terminal.

Inspect with MCP Inspector

Another way is to use the official MCP Inspector to inspect your server with a Web UI:

bash
npx litemcp inspect server.js

SSE Transport

The servers are running with stdio transport by default. You can also run the server with SSE mode:

js
server.start({
  transportType: "sse",
  sse: {
    endpoint: "/sse",
    port: 8080,
  },
});

This will start the server and listen for SSE connections on http://localhost:8080/sse.

You can then connect to the server with SSE transport in the client.

Showcase

If you've developed a server using LiteMCP, please submit a PR to showcase it here!

• https://github.com/wong2/mcp-jina-reader
• https://github.com/nloui/paperless-mcp

Roadmap

• Add support for Resource Templates

Related

• mcp-cli - A CLI for testing and debugging MCP servers
• mcpservers.org - A curated list of MCP servers
• FastMCP - A Python library for MCP server development, inspiration for this project