Skip to content

Commit 469a203

Browse files
author
vcart
committed
chore: adding more detailed docs
1 parent 997883b commit 469a203

1 file changed

Lines changed: 206 additions & 34 deletions

File tree

‎README.md‎

Lines changed: 206 additions & 34 deletions
Original file line numberDiff line numberDiff line change
@@ -2,9 +2,8 @@
22

33
![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)
44
![TypeScript](https://img.shields.io/badge/TypeScript-5.0+-3178C6)
5-
![MCP](https://img.shields.io/badge/MCP-1.7+-green)
65

7-
A CLI tool to quickly get started building your very own MCP (Model Context Protocol) server.
6+
A CLI tool to quickly get started building your very own MCP (Model Context Protocol) server using FastMCP.
87

98
## 📋 Usage
109

@@ -13,23 +12,23 @@ A CLI tool to quickly get started building your very own MCP (Model Context Prot
1312
npx @mcpdotdirect/create-mcp-server
1413

1514
# Or with npm
16-
npm init @mcpdotdirect/create-mcp-server
15+
npm init @mcpdotdirect/mcp-server
1716
```
1817

1918
## 🔭 What's Included
2019

2120
The template includes:
2221

23-
- Basic server setup with both stdio and HTTP transport options
22+
- Basic server setup with both stdio and HTTP transport options using FastMCP
2423
- Structure for defining MCP tools, resources, and prompts
2524
- TypeScript configuration
2625
- Development scripts and configuration
2726

2827
## ✨ Features
2928

29+
- **FastMCP**: Built using the FastMCP framework for simpler implementation
3030
- **Dual Transport Support**: Run your MCP server over stdio or HTTP
3131
- **TypeScript**: Full TypeScript support for type safety
32-
- **MCP SDK**: Built on the official Model Context Protocol SDK
3332
- **Extensible**: Easy to add custom tools, resources, and prompts
3433

3534
## 🚀 Getting Started
@@ -71,41 +70,214 @@ After creating your project:
7170

7271
> **Note**: The default scripts in package.json use Bun as the runtime (e.g., `bun run src/index.ts`). If you prefer to use a different package manager or runtime, you can modify these scripts in your package.json file to use Node.js or another runtime of your choice.
7372
73+
## 📖 Detailed Usage
74+
75+
### Transport Methods
76+
77+
The MCP server supports two transport methods:
78+
79+
1. **stdio Transport** (Command Line Mode):
80+
- Runs on your **local machine**
81+
- Managed automatically by Cursor
82+
- Communicates directly via `stdout`
83+
- Only accessible by you locally
84+
- Ideal for personal development and tools
85+
86+
2. **SSE Transport** (HTTP Web Mode):
87+
- Can run **locally or remotely**
88+
- Managed and run by you
89+
- Communicates **over the network**
90+
- Can be **shared** across machines
91+
- Ideal for team collaboration and shared tools
92+
93+
### Running the Server Locally
94+
95+
#### stdio Transport (CLI Mode)
96+
97+
Start the server in stdio mode for CLI tools:
98+
99+
```bash
100+
# Start the stdio server
101+
npm start
102+
# or with other package managers
103+
yarn start
104+
pnpm start
105+
bun start
106+
107+
# Start the server in development mode with auto-reload
108+
npm run dev
109+
# or
110+
yarn dev
111+
pnpm dev
112+
bun dev
113+
```
114+
115+
#### HTTP Transport (Web Mode)
116+
117+
Start the server in HTTP mode for web applications:
118+
119+
```bash
120+
# Start the HTTP server
121+
npm run start:http
122+
# or
123+
yarn start:http
124+
pnpm start:http
125+
bun start:http
126+
127+
# Start the HTTP server in development mode with auto-reload
128+
npm run dev:http
129+
# or
130+
yarn dev:http
131+
pnpm dev:http
132+
bun dev:http
133+
```
134+
135+
By default, the HTTP server runs on port 3001. You can change this by setting the PORT environment variable:
136+
137+
```bash
138+
# Start the HTTP server on a custom port
139+
PORT=8080 npm run start:http
140+
```
141+
142+
### Connecting to the Server
143+
144+
#### Connecting from Cursor
145+
146+
To connect to your MCP server from Cursor:
147+
148+
1. Open Cursor and go to Settings (gear icon in the bottom left)
149+
2. Click on "Features" in the left sidebar
150+
3. Scroll down to "MCP Servers" section
151+
4. Click "Add new MCP server"
152+
5. Enter the following details:
153+
- Server name: `my-mcp-server` (or any name you prefer)
154+
- For stdio mode:
155+
- Type: `command`
156+
- Command: The path to your server executable, e.g., `npm start`
157+
- For SSE mode:
158+
- Type: `url`
159+
- URL: `http://localhost:3001/sse`
160+
6. Click "Save"
161+
162+
#### Using mcp.json with Cursor
163+
164+
For a more portable configuration, create an `.cursor/mcp.json` file in your project's root directory:
165+
166+
```json
167+
{
168+
"mcpServers": {
169+
"my-mcp-stdio": {
170+
"command": "npm",
171+
"args": [
172+
"start"
173+
],
174+
"env": {
175+
"NODE_ENV": "development"
176+
}
177+
},
178+
"my-mcp-sse": {
179+
"url": "http://localhost:3001/sse"
180+
}
181+
}
182+
}
183+
```
184+
185+
You can also create a global configuration at `~/.cursor/mcp.json` to make your MCP servers available in all your Cursor workspaces.
186+
187+
Note:
188+
- The `command` type entries run the server in stdio mode
189+
- The `url` type entry connects to the HTTP server using SSE transport
190+
- You can provide environment variables using the `env` field
191+
- When connecting via SSE with FastMCP, use the full URL including the `/sse` path: `http://localhost:3001/sse`
192+
193+
### Testing Your Server with CLI Tools
194+
195+
FastMCP provides built-in tools for testing your server:
196+
197+
```bash
198+
# Test with mcp-cli
199+
npx fastmcp dev server.js
200+
201+
# Inspect with MCP Inspector
202+
npx fastmcp inspect server.ts
203+
```
204+
205+
### Using Environment Variables
206+
207+
You can customize the server using environment variables:
208+
209+
```bash
210+
# Change the HTTP port (default is 3001)
211+
PORT=8080 npm run start:http
212+
213+
# Change the host binding (default is 0.0.0.0)
214+
HOST=127.0.0.1 npm run start:http
215+
```
216+
74217
## 🛠️ Adding Custom Tools and Resources
75218

76-
When adding custom tools, resources, or prompts to your MCP server:
77-
78-
1. Use underscores (`_`) instead of hyphens (`-`) in all resource, tool, and prompt names
79-
```typescript
80-
// Good: Uses underscores
81-
server.tool(
82-
"my_custom_tool",
83-
"Description of my custom tool",
84-
{
85-
param_name: z.string().describe("Parameter description")
86-
},
87-
async (params) => {
88-
// Tool implementation
89-
}
90-
);
91-
92-
// Bad: Uses hyphens, may cause issues with Cursor
93-
server.tool(
94-
"my-custom-tool",
95-
"Description of my custom tool",
96-
{
97-
param-name: z.string().describe("Parameter description")
98-
},
99-
async (params) => {
100-
// Tool implementation
101-
}
102-
);
103-
```
219+
When adding custom tools, resources, or prompts to your FastMCP server:
220+
221+
### Tools
222+
223+
```typescript
224+
server.addTool({
225+
name: "hello_world",
226+
description: "A simple hello world tool",
227+
parameters: z.object({
228+
name: z.string().describe("Name to greet")
229+
}),
230+
execute: async (params) => {
231+
return `Hello, ${params.name}!`;
232+
}
233+
});
234+
```
104235

105-
2. This naming convention ensures compatibility with Cursor and other AI tools that interact with your MCP server
236+
### Resources
237+
238+
```typescript
239+
server.addResourceTemplate({
240+
uriTemplate: "example://{id}",
241+
name: "Example Resource",
242+
mimeType: "text/plain",
243+
arguments: [
244+
{
245+
name: "id",
246+
description: "Resource ID",
247+
required: true,
248+
},
249+
],
250+
async load({ id }) {
251+
return {
252+
text: `This is an example resource with ID: ${id}`
253+
};
254+
}
255+
});
256+
```
257+
258+
### Prompts
259+
260+
```typescript
261+
server.addPrompt({
262+
name: "greeting",
263+
description: "A simple greeting prompt",
264+
arguments: [
265+
{
266+
name: "name",
267+
description: "Name to greet",
268+
required: true,
269+
},
270+
],
271+
load: async ({ name }) => {
272+
return `Hello, ${name}! How can I help you today?`;
273+
}
274+
});
275+
```
106276

107277
## 📚 Documentation
108278

279+
For more information about FastMCP, visit [FastMCP GitHub Repository](https://github.com/punkpeye/fastmcp).
280+
109281
For more information about the Model Context Protocol, visit the [MCP Documentation](https://modelcontextprotocol.io/introduction).
110282

111283
## 📄 License

0 commit comments

Comments
 (0)