LiteMCP

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

> Deprecate notice:
>
> Since the official SDK already offers a high-level API similar to this project, this project will no longer be maintained.
>
> If you like the CLI commands in this project, you can use them independently: https://github.com/wong2/mcp-cli

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

npm install litemcp zod

Quickstart

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:

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.

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.

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:

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.

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

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:

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:

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:

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