fastmcp 1.0.0 → 1.0.1

package/.github/workflows/feature.yaml

@@ -0,0 +1,37 @@
+name: Run Tests
+on:
+  pull_request:
+    branches:
+      - main
+    types:
+      - opened
+      - synchronize
+      - reopened
+      - ready_for_review
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    name: Test
+    strategy:
+      fail-fast: true
+      matrix:
+        node:
+          - 22
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+      - uses: pnpm/action-setup@v4
+        with:
+          version: 9
+      - name: Setup NodeJS ${{ matrix.node }}
+        uses: actions/setup-node@v4
+        with:
+          node-version: ${{ matrix.node }}
+          cache: "pnpm"
+          cache-dependency-path: "**/pnpm-lock.yaml"
+      - name: Install dependencies
+        run: pnpm install
+      - name: Run tests
+        run: pnpm test

package/.github/workflows/main.yaml

@@ -0,0 +1,45 @@
+name: Release
+on:
+  push:
+    branches:
+      - main
+jobs:
+  test:
+    environment: release
+    name: Test
+    strategy:
+      fail-fast: true
+      matrix:
+        node:
+          - 22
+    runs-on: ubuntu-latest
+    steps:
+      - name: setup repository
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+      - uses: pnpm/action-setup@v4
+        with:
+          version: 9
+      - name: setup node.js
+        uses: actions/setup-node@v4
+        with:
+          cache: "pnpm"
+          node-version: ${{ matrix.node }}
+      - name: Setup NodeJS ${{ matrix.node }}
+        uses: actions/setup-node@v4
+        with:
+          node-version: ${{ matrix.node }}
+          cache: "pnpm"
+          cache-dependency-path: "**/pnpm-lock.yaml"
+      - name: Install dependencies
+        run: pnpm install
+      - name: Run tests
+        run: pnpm test
+      - name: Build
+        run: pnpm build
+      - name: Release
+        run: pnpm semantic-release
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          NPM_TOKEN: ${{ secrets.NPM_TOKEN }}

package/LICENSE

@@ -0,0 +1,25 @@
+The MIT License (MIT)
+=====================
+
+Copyright © 2024 Frank Fiegel (frank@glama.ai)
+
+Permission is hereby granted, free of charge, to any person
+obtaining a copy of this software and associated documentation
+files (the “Software”), to deal in the Software without
+restriction, including without limitation the rights to use,
+copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the
+Software is furnished to do so, subject to the following
+conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES
+OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
+HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
+WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
+OTHER DEALINGS IN THE SOFTWARE.

package/README.md

@@ -0,0 +1,197 @@
+# FastMCP
+
+A TypeScript framework for building [MCP](https://modelcontextprotocol.io/) servers.
+
+> [!NOTE]
+> For a Python implementation, see [FastMCP](https://github.com/jlowin/fastmcp).
+
+## Features
+
+- Simple Tool, Resource, Prompt definition
+- Full TypeScript support
+- Built-in error handling
+- Built-in CLI for testing and debugging
+- Built-in support for SSE
+
+## Installation
+
+```bash
+npm install fastmcp
+```
+
+## Quickstart
+
+```ts
+import { FastMCP } from "fastmcp";
+import { z } from "zod";
+
+const server = new FastMCP({
+  name: "My Server",
+  version: "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.start({
+  transportType: "stdio",
+});
+```
+
+You can test the server in terminal with:
+
+```bash
+npx fastmcp dev server.js
+```
+
+### SSE
+
+You can also run the server with SSE support:
+
+```ts
+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 use `SSEClientTransport` to connect to the server:
+
+```ts
+import { SSEClientTransport } from "@modelcontextprotocol/sdk/client/sse.js";
+
+const client = new Client(
+  {
+    name: "example-client",
+    version: "1.0.0",
+  },
+  {
+    capabilities: {},
+  },
+);
+
+const transport = new SSEClientTransport(new URL(`http://localhost:8080/sse`));
+
+await client.connect(transport);
+```
+
+## Core Concepts
+
+### Tools
+
+[Tools](https://modelcontextprotocol.io/docs/concepts/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](https://modelcontextprotocol.io/docs/concepts/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](https://modelcontextprotocol.io/docs/concepts/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}`;
+  },
+});
+```
+
+## Running Your Server
+
+### Test with `mcp-cli`
+
+The fastest way to test and debug your server is with `fastmcp dev`:
+
+```bash
+npx fastmcp dev server.js
+npx fastmcp dev server.ts
+```
+
+This will run your server with [`mcp-cli`](https://github.com/wong2/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`](https://modelcontextprotocol.io/docs/tools/inspector) to inspect your server with a Web UI:
+
+```bash
+npx fastmcp inspect server.ts
+```
+
+## Showcase
+
+> [!NOTE]
+> If you've developed a server using FastMCP, please [submit a PR](https://github.com/punkpeye/fastmcp) to showcase it here!
+
+## Acknowledgements
+
+- FastMCP is inspired by the [Python implementation](https://github.com/jlowin/fastmcp) by [Jonathan Lowin](https://github.com/jlowin).
+- Parts of codebase were adopted from [LiteMCP](https://github.com/wong2/litemcp).
+- Parts of codebase were adopted from [Model Context protocolでSSEをやってみる](https://dev.classmethod.jp/articles/mcp-sse/).

package/dist/FastMCP.d.ts

@@ -0,0 +1,69 @@
+import { z } from 'zod';
+
+type ToolParameters = z.ZodTypeAny;
+type Tool<Params extends ToolParameters = ToolParameters> = {
+    name: string;
+    description?: string;
+    parameters?: Params;
+    execute: (args: z.infer<Params>) => Promise<unknown>;
+};
+type Resource = {
+    uri: string;
+    name: string;
+    description?: string;
+    mimeType?: string;
+    load: () => Promise<{
+        text: string;
+    } | {
+        blob: string;
+    }>;
+};
+type PromptArgument = Readonly<{
+    name: string;
+    description?: string;
+    required?: boolean;
+}>;
+type ArgumentsToObject<T extends PromptArgument[]> = {
+    [K in T[number]["name"]]: Extract<T[number], {
+        name: K;
+    }>["required"] extends true ? string : string | undefined;
+};
+type Prompt<Arguments extends PromptArgument[] = PromptArgument[], Args = ArgumentsToObject<Arguments>> = {
+    name: string;
+    description?: string;
+    arguments?: Arguments;
+    load: (args: Args) => Promise<string>;
+};
+type ServerOptions = {
+    name: string;
+    version: `${number}.${number}.${number}`;
+};
+declare class FastMCP {
+    #private;
+    options: ServerOptions;
+    constructor(options: ServerOptions);
+    private setupHandlers;
+    private setupErrorHandling;
+    private setupToolHandlers;
+    private setupResourceHandlers;
+    private setupPromptHandlers;
+    addTool<Params extends ToolParameters>(tool: Tool<Params>): void;
+    addResource(resource: Resource): void;
+    addPrompt<const Args extends PromptArgument[]>(prompt: Prompt<Args>): void;
+    start(options?: {
+        transportType: "stdio";
+    } | {
+        transportType: "sse";
+        sse: {
+            endpoint: `/${string}`;
+            port: number;
+        };
+    }): Promise<void>;
+    /**
+     * @see https://dev.classmethod.jp/articles/mcp-sse/
+     */
+    private startSending;
+    stop(): Promise<void>;
+}
+
+export { FastMCP };

package/dist/FastMCP.js

@@ -0,0 +1,318 @@
+// src/FastMCP.ts
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { SSEServerTransport } from "@modelcontextprotocol/sdk/server/sse.js";
+import {
+  CallToolRequestSchema,
+  ErrorCode,
+  GetPromptRequestSchema,
+  ListPromptsRequestSchema,
+  ListResourcesRequestSchema,
+  ListToolsRequestSchema,
+  McpError,
+  ReadResourceRequestSchema
+} from "@modelcontextprotocol/sdk/types.js";
+import { zodToJsonSchema } from "zod-to-json-schema";
+import http from "http";
+var FastMCP = class {
+  constructor(options) {
+    this.options = options;
+    this.#options = options;
+    this.#tools = [];
+    this.#resources = [];
+    this.#prompts = [];
+  }
+  #tools;
+  #resources;
+  #prompts;
+  #server = null;
+  #options;
+  setupHandlers(server) {
+    this.setupErrorHandling(server);
+    if (this.#tools.length) {
+      this.setupToolHandlers(server);
+    }
+    if (this.#resources.length) {
+      this.setupResourceHandlers(server);
+    }
+    if (this.#prompts.length) {
+      this.setupPromptHandlers(server);
+    }
+  }
+  setupErrorHandling(server) {
+    server.onerror = (error) => {
+      console.error("[MCP Error]", error);
+    };
+    process.on("SIGINT", async () => {
+      await server.close();
+      process.exit(0);
+    });
+  }
+  setupToolHandlers(server) {
+    server.setRequestHandler(ListToolsRequestSchema, async () => {
+      return {
+        tools: this.#tools.map((tool) => {
+          return {
+            name: tool.name,
+            description: tool.description,
+            inputSchema: tool.parameters ? zodToJsonSchema(tool.parameters) : void 0
+          };
+        })
+      };
+    });
+    server.setRequestHandler(CallToolRequestSchema, async (request) => {
+      const tool = this.#tools.find(
+        (tool2) => tool2.name === request.params.name
+      );
+      if (!tool) {
+        throw new McpError(
+          ErrorCode.MethodNotFound,
+          `Unknown tool: ${request.params.name}`
+        );
+      }
+      let args = void 0;
+      if (tool.parameters) {
+        const parsed = tool.parameters.safeParse(request.params.arguments);
+        if (!parsed.success) {
+          throw new McpError(
+            ErrorCode.InvalidRequest,
+            `Invalid ${request.params.name} arguments`
+          );
+        }
+        args = parsed.data;
+      }
+      let result;
+      try {
+        result = await tool.execute(args);
+      } catch (error) {
+        return {
+          content: [{ type: "text", text: `Error: ${error}` }],
+          isError: true
+        };
+      }
+      if (typeof result === "string") {
+        return {
+          content: [{ type: "text", text: result }]
+        };
+      }
+      return {
+        content: [{ type: "text", text: JSON.stringify(result, null, 2) }]
+      };
+    });
+  }
+  setupResourceHandlers(server) {
+    server.setRequestHandler(ListResourcesRequestSchema, async () => {
+      return {
+        resources: this.#resources.map((resource) => {
+          return {
+            uri: resource.uri,
+            name: resource.name,
+            mimeType: resource.mimeType
+          };
+        })
+      };
+    });
+    server.setRequestHandler(ReadResourceRequestSchema, async (request) => {
+      const resource = this.#resources.find(
+        (resource2) => resource2.uri === request.params.uri
+      );
+      if (!resource) {
+        throw new McpError(
+          ErrorCode.MethodNotFound,
+          `Unknown resource: ${request.params.uri}`
+        );
+      }
+      let result;
+      try {
+        result = await resource.load();
+      } catch (error) {
+        throw new McpError(
+          ErrorCode.InternalError,
+          `Error reading resource: ${error}`,
+          {
+            uri: resource.uri
+          }
+        );
+      }
+      return {
+        contents: [
+          {
+            uri: resource.uri,
+            mimeType: resource.mimeType,
+            ...result
+          }
+        ]
+      };
+    });
+  }
+  setupPromptHandlers(server) {
+    server.setRequestHandler(ListPromptsRequestSchema, async () => {
+      return {
+        prompts: this.#prompts.map((prompt) => {
+          return {
+            name: prompt.name,
+            description: prompt.description,
+            arguments: prompt.arguments
+          };
+        })
+      };
+    });
+    server.setRequestHandler(GetPromptRequestSchema, async (request) => {
+      const prompt = this.#prompts.find(
+        (prompt2) => prompt2.name === request.params.name
+      );
+      if (!prompt) {
+        throw new McpError(
+          ErrorCode.MethodNotFound,
+          `Unknown prompt: ${request.params.name}`
+        );
+      }
+      const args = request.params.arguments;
+      if (prompt.arguments) {
+        for (const arg of prompt.arguments) {
+          if (arg.required && !(args && arg.name in args)) {
+            throw new McpError(
+              ErrorCode.InvalidRequest,
+              `Missing required argument: ${arg.name}`
+            );
+          }
+        }
+      }
+      let result;
+      try {
+        result = await prompt.load(args);
+      } catch (error) {
+        throw new McpError(
+          ErrorCode.InternalError,
+          `Error loading prompt: ${error}`
+        );
+      }
+      return {
+        description: prompt.description,
+        messages: [
+          {
+            role: "user",
+            content: { type: "text", text: result }
+          }
+        ]
+      };
+    });
+  }
+  addTool(tool) {
+    this.#tools.push(tool);
+  }
+  addResource(resource) {
+    this.#resources.push(resource);
+  }
+  addPrompt(prompt) {
+    this.#prompts.push(prompt);
+  }
+  #httpServer = null;
+  async start(options = {
+    transportType: "stdio"
+  }) {
+    const capabilities = {};
+    if (this.#tools.length) {
+      capabilities.tools = {};
+    }
+    if (this.#resources.length) {
+      capabilities.resources = {};
+    }
+    if (this.#prompts.length) {
+      capabilities.prompts = {};
+    }
+    this.#server = new Server(
+      { name: this.#options.name, version: this.#options.version },
+      { capabilities }
+    );
+    this.setupHandlers(this.#server);
+    if (options.transportType === "stdio") {
+      const transport = new StdioServerTransport();
+      await this.#server.connect(transport);
+      console.error(`server is running on stdio`);
+    } else if (options.transportType === "sse") {
+      let activeTransport = null;
+      this.#httpServer = http.createServer(async (req, res) => {
+        if (req.method === "GET" && req.url === options.sse.endpoint) {
+          const transport = new SSEServerTransport("/messages", res);
+          activeTransport = transport;
+          if (!this.#server) {
+            throw new Error("Server not initialized");
+          }
+          await this.#server.connect(transport);
+          res.on("close", () => {
+            console.log("SSE connection closed");
+            if (activeTransport === transport) {
+              activeTransport = null;
+            }
+          });
+          this.startSending(transport);
+          return;
+        }
+        if (req.method === "POST" && req.url?.startsWith("/messages")) {
+          if (!activeTransport) {
+            res.writeHead(400).end("No active transport");
+            return;
+          }
+          await activeTransport.handlePostMessage(req, res);
+          return;
+        }
+        res.writeHead(404).end();
+      });
+      this.#httpServer.listen(options.sse.port, "0.0.0.0");
+      console.error(
+        `server is running on SSE at http://localhost:${options.sse.port}${options.sse.endpoint}`
+      );
+    } else {
+      throw new Error("Invalid transport type");
+    }
+  }
+  /**
+   * @see https://dev.classmethod.jp/articles/mcp-sse/
+   */
+  async startSending(transport) {
+    try {
+      await transport.send({
+        jsonrpc: "2.0",
+        method: "sse/connection",
+        params: { message: "SSE Connection established" }
+      });
+      let messageCount = 0;
+      const interval = setInterval(async () => {
+        messageCount++;
+        const message = `Message ${messageCount} at ${(/* @__PURE__ */ new Date()).toISOString()}`;
+        try {
+          await transport.send({
+            jsonrpc: "2.0",
+            method: "sse/message",
+            params: { data: message }
+          });
+          console.log(`Sent: ${message}`);
+          if (messageCount === 10) {
+            clearInterval(interval);
+            await transport.send({
+              jsonrpc: "2.0",
+              method: "sse/complete",
+              params: { message: "Stream completed" }
+            });
+            console.log("Stream completed");
+          }
+        } catch (error) {
+          console.error("Error sending message:", error);
+          clearInterval(interval);
+        }
+      }, 1e3);
+    } catch (error) {
+      console.error("Error in startSending:", error);
+    }
+  }
+  async stop() {
+    if (this.#httpServer) {
+      this.#httpServer.close();
+    }
+  }
+};
+export {
+  FastMCP
+};
+//# sourceMappingURL=FastMCP.js.map