Skip to content
Back to search

easy-mcp

Absurdly easy Model Context Protocol Servers in Typescript

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/zcaceres--easy-mcp/badge.svg)](/listings/zcaceres--easy-mcp)

HTML

<a href="/listings/zcaceres--easy-mcp"><img src="/api/listings/zcaceres--easy-mcp/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

To install EasyMCP, run the following command in your project directory:

bun install

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 414 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. # easy-mcp
  2. ![easyMCP logo](./assets/logo.webp)
  3. > EasyMCP is usable but in beta. Please report any issues you encounter.
  4. EasyMCP is the simplest way to create Model Context Protocol (MCP) servers in TypeScript.
  5. It hides the plumbing, formatting, and other boilerplate definitions behind simple declarations.
  6. Easy MCP allows you to define the bare minimum of what you need to get started. Or you can define more complex resources, templates, tools, and prompts.
  7. ## Features
  8. - **Simple Express-like API**: EasyMCP provides a high-level, intuitive API. Define Tools, Prompts, Resources, Resource Templates, and Roots with calls similar to defining endpoints in ExpressJS. Every possible parameter that could be optional is optional and hidden unless you need it.
  9. - **Experimental Decorators API**: Automagically infers tool, prompt, and resource arguments. No input schema definition required!
  10. - **Context Object**: Access MCP capabilities like logging and progress reporting through a context object in your tools.
  11. - **Great Type Safety**: Better DX and fewer runtime errors.
  12. ## Beta Limitations
  13. - No support for MCP sampling, yet
  14. - No support for SSE, yet
  15. - No resource update notifications, yet
  16. - Prompts technically accept inputs, but the Typescript SDK suggests they can't. So this functionality feels unfinished.
  17. ## Installation
  18. To install EasyMCP, run the following command in your project directory:
  19. ```bash
  20. bun install
  21. ```
  22. ## Quick Start with (Experimental) Decorators API
  23. Also see `examples/express-decorators.ts` or run `bun start:decorators`
  24. EasyMCP's decorator API is dead simple and infers types and input configuration automatically.
  25. But it's *experimental* and may change or have not-yet-discovered problems.
  26. ```typescript
  27. import EasyMCP from "./lib/EasyMCP";
  28. import { Tool, Resource, Prompt } from "./lib/experimental/decorators";
  29. class MyMCP extends EasyMCP {
  30. @Resource("greeting/{name}")
  31. getGreeting(name: string) {
  32. return `Hello, ${name}!`;
  33. }
  34. @Prompt()
  35. greetingPrompt(name: string) {
  36. return `Generate a greeting for ${name}.`;
  37. }
  38. @Tool()
  39. greet(name: string, optionalContextFromServer: Context) {
  40. optionalContextFromServer.info(`Greeting ${name}`);
  41. return `Hello, ${name}!`;
  42. }
  43. }
  44. const mcp = new MyMCP({ version: "1.0.0" });
  45. ```
  46. ## Complex Example with Decorators API
  47. See `examples/express-express.ts` or run `bun start:express`
  48. ```typescript
  49. import EasyMCP from "./lib/EasyMCP";
  50. import { Prompt } from "./lib/decorators/Prompt";
  51. import { Resource } from "./lib/decorators/Resource";
  52. import { Root } from "./lib/decorators/Root";
  53. import { Tool } from "./lib/decorators/Tool";
  54. @Root("/my-sample-dir/photos")
  55. @Root("/my-root-dir", { name: "My laptop's root directory" }) // Optionally you can name the root
  56. class ZachsMCP extends EasyMCP {
  57. /**
  58. You can declare a Tool with zero configuration. Relevant types and plumbing will be inferred and handled.
  59. By default, the name of the Tool will be the name of the method.
  60. */
  61. @Tool()
  62. simpleFunc(nickname: string, height: number) {
  63. return `${nickname} of ${height} height`;
  64. }
  65. /**
  66. * You can enhance a tool with optional data like a description.
  67. Due to limitations in Typescript, if you want the Tool to serialize certain inputs as optional to the Client, you need to provide an optionals list.
  68. */
  69. @Tool({
  70. description: "An optional description",
  71. optionals: ["active", "items", "age"],
  72. })
  73. middleFunc(name: string, active?: string, items?: string[], age?: number) {
  74. return `exampleFunc called: name ${name}, active ${active}, items ${items}, age ${age}`;
  75. }
  76. /**
  77. * You can also provide a schema for the input arguments of a tool, if you want full control.
  78. */
  79. @Tool({
  80. description: "A function with various parameter types",
  81. parameters: [
  82. {
  83. name: "date",
  84. type: "string",
  85. optional: false,
  86. },
  87. {
  88. name: "season",
  89. type: "string",
  90. optional: false,
  91. },
  92. {
  93. name: "year",
  94. type: "number",
  95. optional: true,
  96. },
  97. ],
  98. })
  99. complexTool(date: string, season: string, year?: number) {
  100. return `complexTool called: date ${date}, season ${season}, year ${year}`;
  101. }
  102. /**
  103. * Tools can use a context object to access MCP capabilities like logging, progress reporting, and meta data from the request
  104. */
  105. @Tool({
  106. description: "A tool that uses context",
  107. })
  108. async processData(dataSource: string, context: Context) {
  109. context.info(`Starting to process data from ${dataSource}`);
  110. try {
  111. const data = await context.readResource(dataSource);
  112. context.debug("Data loaded");
  113. for (let i = 0; i < 5; i++) {
  114. await new Promise((resolve) => setTimeout(resolve, 1000));
  115. await context.reportProgress(i * 20, 100);
  116. context.info(`Processing step ${i + 1} complete`);
  117. }
  118. return `Processed ${data.length} bytes of data from ${dataSource}`;
  119. } catch (error) {
  120. context.error(`Error processing data: ${(error as Error).message}`);
  121. throw error;
  122. }
  123. }
  124. /**
  125. * Resources can be declared with a simple URI.
  126. By default, the name of the resource will be the name of the method.
  127. */
  128. @Resource("simple-resource")
  129. simpleResource() {
  130. return "Hello, world!";
  131. }
  132. /**
  133. * Or include handlebars which EasyMCP will treat as a Resource Template.
  134. Both Resources and Resource Templates can be configured with optional data like a description.
  135. */
  136. @Resource("greeting/{name}")
  137. myResourceTemplate(name: string) {
  138. return `Hello, ${name}!`;
  139. }
  140. /**
  141. * By default, prompts need no configuration.
  142. They will be named after the method they decorate.
  143. */
  144. @Prompt()
  145. simplePrompt(name: string) {
  146. return `Prompting... ${name}`;
  147. }
  148. /**
  149. * Or you can override and configure a Prompt with a name, description, and explicit arguments.
  150. */
  151. @Prompt({
  152. name: "configured-prompt",
  153. description: "A prompt with a name and description",
  154. args: [
  155. {
  156. name: "name",
  157. description: "The name of the thing to prompt",
  158. required: true,
  159. },
  160. ],
  161. })
  162. configuredPrompt(name: string) {
  163. return `Prompting... ${name}`;
  164. }
  165. }
  166. const mcp = new ZachsMCP({ version: "1.0.0" });
  167. console.log(mcp.name, "is now serving!");
  168. ```
  169. ## Quick Start with Express-like API
  170. Also see `examples/example-minimal.ts` or run `bun start:express`
  171. This API is more verbose and less magical, but it's more stable and tested.
  172. ```typescript
  173. import EasyMCP from "easy-mcp";
  174. const mcp = EasyMCP.create("my-mcp-server", {
  175. version: "0.1.0",
  176. });
  177. // Define a resource
  178. mcp.resource({
  179. uri: "dir://desktop",
  180. name: "Desktop Directory", // Optional
  181. description: "Lists files on the desktop", // Optional
  182. mimeType: "text/plain", // Optional
  183. fn: async () => {
  184. return "file://desktop/file1.txt\nfile://desktop/file2.txt";
  185. },
  186. });
  187. // Define a resource template
  188. mcp.template({
  189. uriTemplate: "file://{filename}",
  190. name: "File Template", // Optional
  191. description: "Template for accessing files", // Optional
  192. mimeType: "text/plain", // Optional
  193. fn: async ({ filename }) => {
  194. return `Contents of ${filename}`;
  195. },
  196. });
  197. // Define a tool
  198. mcp.tool({
  199. name: "greet",
  200. description: "Greets a person", // Optional
  201. inputs: [ // Optional
  202. {
  203. name: "name",
  204. type: "string",
  205. description: "The name to greet",
  206. required: true,
  207. },
  208. ],
  209. fn: async ({ name }) => {
  210. return `Hello, ${name}!`;
  211. },
  212. });
  213. // Define a prompt
  214. mcp.prompt({
  215. name: "introduction",
  216. description: "Generates an introduction", // Optional
  217. args: [ // Optional
  218. {
  219. name: "name",
  220. type: "string",
  221. description: "Your name",
  222. required: true,
  223. },
  224. ],
  225. fn: async ({ name }) => {
  226. return `Hi there! My name is ${name}. It's nice to meet you!`;
  227. },
  228. });
  229. // Start the server
  230. mcp.serve().catch(console.error);
  231. ```
  232. ## Express-Like API
  233. ### `EasyMCP.create(name: string, options: ServerOptions)`
  234. Creates a new EasyMCP instance.
  235. - `name`: The name of your MCP server.
  236. - `options`: Server options, including the version.
  237. ### `mcp.resource(config: ResourceConfig)`
  238. Defines a resource.
  239. ### `mcp.template(config: ResourceTemplateConfig)`
  240. Defines a resource template.
  241. ### `mcp.tool(config: ToolConfig)`
  242. Defines a tool.
  243. ### `mcp.prompt(config: PromptConfig)`
  244. Defines a prompt.
  245. ### `mcp.root(config: Root)`
  246. Defines a root.
  247. ### `mcp.serve()`
  248. Starts the MCP server.
  249. ## (Experimental) Decorator API
  250. EasyMCP provides decorators for a more concise and declarative way to define your MCP server components. Here's an overview of the available decorators:
  251. ### `@Tool(config?: ToolConfig)`
  252. Defines a method as a tool. The method will take in any arguments you declare and infer types and input configurations based on your TS annotations. An optional `context` argument can be added as the last argument to access MCP capabilities.
  253. - `config`: Optional configuration object for the tool.
  254. - `description`: Optional description of the tool.
  255. - `optionals`: Optional array of parameter names that should be marked as optional.
  256. - `parameters`: Optional array of parameter definitions for full control over the input schema.
  257. Example:
  258. ```typescript
  259. @Tool({
  260. description: "Greets a person",
  261. optionals: ["title"],
  262. })
  263. greet(name: string, title?: string, optionalContext: Context) {
  264. return `Hello, ${title ? title + " " : ""}${name}!`;
  265. }
  266. ```
  267. ### `@Resource(uri: string, config?: Partial<ResourceDefinition>)`
  268. Defines a method as a resource or resource template. A resource template is defined by using handlebars in the URI.
  269. - `uri`: The URI or URI template for the resource.
  270. - `config`: Optional configuration object for the resource.
  271. - `name`: Optional name for the resource.
  272. - `description`: Optional description of the resource.
  273. - `mimeType`: Optional MIME type of the resource.
  274. Example:
  275. ```typescript
  276. @Resource("greeting/{name}")
  277. getGreeting(name: string) {
  278. return `Hello, ${name}!`;
  279. }
  280. ```
  281. ### `@Prompt(config?: PromptDefinition)`
  282. Defines a method as a prompt.
  283. - `config`: Optional configuration object for the prompt.
  284. - `name`: Optional name for the prompt (defaults to method name).
  285. - `description`: Optional description of the prompt.
  286. - `args`: Optional array of argument definitions.
  287. Example:
  288. ```typescript
  289. @Prompt({
  290. description: "Generates a greeting prompt",
  291. args: [
  292. { name: "name", description: "Name to greet", required: true },
  293. ],
  294. })
  295. greetingPrompt(name: string) {
  296. return `Generate a friendly greeting for ${name}.`;
  297. }
  298. ```
  299. ### `@Root(uri: string, config?: { name?: string })`
  300. Defines a root directory for the MCP server. This decorator is applied to the class, not to a method.
  301. - `uri`: The URI of the root directory.
  302. - `config`: Optional configuration object.
  303. - `name`: Optional name for the root.
  304. Example:
  305. ```typescript
  306. @Root("/my-sample-dir/photos")
  307. @Root("/my-root-dir", { name: "My laptop's root directory" })
  308. class MyMCP extends EasyMCP {
  309. // ...
  310. }
  311. ```
  312. > When using decorators, EasyMCP will automatically infer types and create appropriate configurations for your tools, resources, prompts, and roots. This can significantly reduce boilerplate code and make your MCP server definition more concise.
  313. But... the decorator API is experimental and may have bugs or unexpected changes
  314. ## Contributing
  315. Contributions are welcome! Just submit a PR.
  316. ## License
  317. This project is licensed under the MIT License.
  318. ## Credits
  319. EasyMCP was created by [Zach Caceres](https://www.zach.dev) but inspired by [FastMCP by kjlowin](https://github.com/jlowin/fastmcp), a library for Python MCP servers.

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.