What is Mcp Server Starter

mcp-server-starter is a minimal starter template designed for building Model Context Protocol (MCP) servers using TypeScript and FastMCP.

Use cases

Use cases for mcp-server-starter include building weather services, integrating with third-party APIs, and creating scalable server applications that require structured code organization and error handling.

How to use

To use mcp-server-starter, create a new repository from the template, navigate to your project directory, initialize a Git repository, customize the package.json file, install dependencies, configure environment variables, and start developing your server.

Key features

Key features include a basic project structure, TypeScript setup, Biome for linting and formatting, FastMCP for MCP server implementation, a weather service example with proper folder structure, API integration, error handling, parameter validation using Zod, and GitHub Actions workflows for CI and release.

Where to use

mcp-server-starter can be used in various fields that require the development of MCP servers, such as web services, APIs, and cloud applications.

MCP Server Starter Template

A minimal starter template for building Model Context Protocol (MCP) servers using TypeScript and FastMCP.

Features

• Basic project structure with src/lib, src/services, src/tools.
• TypeScript setup (compiles to dist/).
• Biome for linting and formatting.
• fastmcp for MCP server implementation.
• A weather service example demonstrating:
  • Proper folder structure (lib, services, tools)
  • API integration with error handling
  • Parameter validation using Zod
  • Separation of concerns
• GitHub Actions workflows for CI and Release (manual trigger by default).

Getting Started

1. Create a new repository from this template:
   Click here to generate a new repository from this template.

2. Navigate to your new project:

   cd /path/to/your-new-mcp-server
   

3. Initialize Git Repository (if not already):

   git init
   git branch -M main # Or your preferred default branch name
   

4. Customize package.json:

   • Update name, version, description, author, repository, etc.
   • Update the bin entry if you change the command name.

5. Install dependencies:

   pnpm install
   

6. Configure environment variables:
   For the weather service example, you’ll need an OpenWeather API key:

   # Create a .env file (add to .gitignore)
   echo "OPENWEATHER_API_KEY=your_api_key_here" > .env
   

   Get an API key from OpenWeather.

7. Initial Commit:
   It’s a good idea to make an initial commit at this stage before setting up Husky and Changesets.

   git add .
   git commit -m "feat: initial project setup from template"
   

8. Develop your server:

   • Add your custom tools in the src/tools/ directory.
   • Implement logic in src/lib/ and src/services/.
   • Register tools in src/index.ts.

Example Weather Tool

This template includes a weather service example that demonstrates:

1. HTTP Utilities (src/lib/http.ts):

   • Type-safe HTTP requests with Zod validation
   • Error handling

2. Configuration (src/lib/config.ts):

   • Environment variable management
   • Service configuration

3. Weather Service (src/services/weatherService.ts):

   • API integration
   • Data transformation
   • Proper error propagation

4. Weather Tool (src/tools/weather.ts):

   • Parameter validation with Zod
   • User-friendly output formatting
   • Error handling and user guidance

To use the weather tool:

# Set your OpenWeather API key
export OPENWEATHER_API_KEY=your_api_key_here

# Run the server
pnpm run start

# Connect with an MCP client and use the GET_WEATHER tool
# with parameter: { "city": "London" }

Pre-commit Linting (Husky & lint-staged)

This template includes husky and lint-staged in its devDependencies for running Biome on staged files before committing. To set it up:

1. Ensure your package.json has the prepare script for husky:

   {
     "scripts": {
       "prepare": "husky"
     }
   }
   

2. Install dependencies and initialize husky:

   pnpm install
   pnpm dlx husky init
   

   This creates a .husky directory with the necessary setup.

3. Create the pre-commit hook for lint-staged:

   # Create or edit the pre-commit file
   echo '#!/usr/bin/env sh' > .husky/pre-commit
   echo '. "$(dirname -- "$0")/_/husky.sh"
   
   pnpm lint-staged' >> .husky/pre-commit
   
   # Make it executable
   chmod +x .husky/pre-commit
   
   

4. Configure lint-staged in package.json:

   Adjust the Biome command as needed. The one above is a common example.

5. Test it:
   Stage some changes to a .ts file and try to commit. Biome should run on the staged file.

Release Management (Changesets)

This template is ready for release management using Changesets.

1. Install Changesets CLI (if not already in devDependencies):
   The template package.json should include @changesets/cli. If not:

   pnpm add -D @changesets/cli
   

2. Initialize Changesets:
   This command will create a .changeset directory with some configuration files.

   pnpm changeset init
   # or npx changeset init
   

   Commit the generated .changeset directory and its contents.

3. Adding Changesets During Development:
   When you make a change that should result in a version bump (fix, feature, breaking change):

   pnpm changeset add
   # or npx changeset add
   

   Follow the prompts. This will create a markdown file in the .changeset directory describing the change.
   Commit this changeset file along with your code changes.

4. Publishing a Release:
   The GitHub Actions workflow release.yml (in mcp-server-starter/.github/workflows/) is set up for this. When you are ready to release:

   • Ensure all feature PRs with their changeset files are merged to main.
   • Important: Before publishing, ensure your package.json is complete. Add or update fields like keywords, author, repository (e.g., "repository": {"type": "git", "url": "https://github.com/YOUR_USERNAME/YOUR_REPO_NAME.git"}), bugs (e.g., "bugs": {"url": "https://github.com/YOUR_USERNAME/YOUR_REPO_NAME/issues"}), and homepage (e.g., "homepage": "https://github.com/YOUR_USERNAME/YOUR_REPO_NAME#readme") for better discoverability and information on npm.
   • The release.yml workflow (manually triggered by default in the template) will:
     1. Run changeset version to consume changeset files, update package.json versions, and update CHANGELOG.md. It will push these to a changeset-release/main branch and open a “Version Packages” PR.
     2. Merge the “Version Packages” PR.
     3. Upon merging, the workflow runs again on main. This time, it will run pnpm run publish-packages (which should include changeset publish) to publish to npm and create GitHub Releases/tags.
   • To enable automatic release flow: Change on: workflow_dispatch in release.yml to on: push: branches: [main] (or your release branch).

Available Scripts

• pnpm run build: Compiles TypeScript to JavaScript in dist/ and makes the output executable.
• pnpm run dev: Runs the server in development mode using tsx (hot-reloading for TypeScript).
• pnpm run start: Runs the built server (from dist/) using Node.
• pnpm run lint: Lints the codebase using Biome.
• pnpm run format: Formats the codebase using Biome.

Using the Server

After building (pnpm run build), you can run the server:

• Directly if linked or globally installed: mcp-hello-server (or your customized bin name).
• Via node: node dist/index.js
• Via pnpm dlx (once published): pnpm dlx your-published-package-name