# mcp-server-starter

Production-ready TypeScript template for building MCP (Model Context Protocol) servers. Works with Claude Code, Cursor, and any MCP client.

## Quick Start

```bash
# Clone the template
git clone https://github.com/fix2015/mcp-server-starter.git my-mcp-server
cd my-mcp-server

# Install dependencies
npm install

# Build
npm run build

# Run the server
npm start
```

## Project Structure

```
src/
  index.ts                 # Server entry point — registers tools, resources, and prompts
  tools/
    example-tool.ts        # Example tool implementation (process_text)
  resources/
    example-resource.ts    # Example resource implementation (server-info)
```

## How to Add a New Tool

Create a new file in `src/tools/`:

```typescript
// src/tools/my-tool.ts
import { z } from "zod";
import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";

export function registerMyTool(server: McpServer): void {
  server.tool(
    "my_tool_name",
    "Description of what the tool does",
    {
      input: z.string().describe("Input parameter description"),
    },
    async ({ input }) => {
      // Your tool logic here
      return {
        content: [{ type: "text", text: `Result: ${input}` }],
      };
    }
  );
}
```

Then register it in `src/index.ts`:

```typescript
import { registerMyTool } from "./tools/my-tool.js";

registerMyTool(server);
```

## How to Add a New Resource

Create a new file in `src/resources/`:

```typescript
// src/resources/my-resource.ts
import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";

export function registerMyResource(server: McpServer): void {
  server.resource("my-resource", "custom://my-data", async (uri) => {
    return {
      contents: [
        {
          uri: uri.href,
          mimeType: "application/json",
          text: JSON.stringify({ key: "value" }),
        },
      ],
    };
  });
}
```

Then register it in `src/index.ts`:

```typescript
import { registerMyResource } from "./resources/my-resource.js";

registerMyResource(server);
```

## Configuration

### Claude Code

Add to your `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "my-server": {
      "command": "node",
      "args": ["/absolute/path/to/my-mcp-server/dist/index.js"]
    }
  }
}
```

### With Environment Variables

```json
{
  "mcpServers": {
    "my-server": {
      "command": "node",
      "args": ["/absolute/path/to/my-mcp-server/dist/index.js"],
      "env": {
        "API_KEY": "your-api-key"
      }
    }
  }
}
```

## Development

```bash
# Watch mode — recompiles on file changes
npm run dev

# Test with the MCP Inspector
npm run inspect
```

## Included Examples

| Type     | Name           | Description                                      |
|----------|----------------|--------------------------------------------------|
| Tool     | `process_text` | Transforms text with uppercase and word counting  |
| Resource | `server-info`  | Returns server metadata as JSON                  |
| Prompt   | `summarize`    | Generates a summary prompt for a given topic     |

## Deployment

### As a Local Server

Build and point your MCP client config to the built `dist/index.js`.

### As an npm Package

1. Update `name` in `package.json` to your package name
2. Run `npm publish`
3. Users can then run: `npx your-package-name`

### With Docker

```dockerfile
FROM node:22-alpine
WORKDIR /app
COPY package*.json ./
RUN npm ci --omit=dev
COPY dist/ ./dist/
ENTRYPOINT ["node", "dist/index.js"]
```

```bash
docker build -t my-mcp-server .
docker run -i my-mcp-server
```

## Requirements

- Node.js >= 18
- TypeScript >= 5.7

## License

MIT