<div align="center">

<img src="https://files.catbox.moe/vumztw.png" alt="ADK TypeScript Logo" width="100" />

<br/>

MCP Server Starter Template

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

MCP • FastMCP • TypeScript

---

</div>

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/).
• 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

The easiest way to create a new MCP server project using this template is with the ADK CLI:

npm install -g @iqai/adk-cli # if you haven't already
adk new --template mcp-starter my-mcp-server
cd my-mcp-server
pnpm install

You can also use this template directly by copying the files, but using the CLI is recommended for best results.

Running the Server

Default (Production/Development) Route

To run your MCP server in production or for standard development, use:

pnpm dev

Fast Iteration & Agent Setup (ADK CLI)

For rapid prototyping, interactive testing, or initial agent setup, use the ADK CLI:

adk run   # Interactive CLI chat with your agents
adk web   # Web interface for easy testing and demonstration

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.

   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/weather-service.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" }

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.

Rapid Development Setup

For fast iteration during development, use the dev script with hot reload:

pnpm run dev

This runs tsx watch src/index.ts which automatically restarts the server when you make changes to your TypeScript files.

MCP Client Configuration for Development

Cursor (.cursor/mcp.json):

{
  "mcpServers": {
    "weather-dev": {
      "command": "/Users/marvelsmbp/Documents/OSS/my-mcp-server/node_modules/.bin/tsx",
      "args": ["watch", "/Users/marvelsmbp/Documents/OSS/my-mcp-server/src/index.ts"],
      "env": {
        "OPENWEATHER_API_KEY": "your_api_key_here"
      }
    }
  }
}

Claude Desktop: Add a development server entry with:

• Command: /Users/marvelsmbp/Documents/OSS/my-mcp-server/node_modules/.bin/tsx
• Args: ["watch", "/Users/marvelsmbp/Documents/OSS/my-mcp-server/src/index.ts"]
• Env: OPENWEATHER_API_KEY=your_api_key_here

Development Workflow

1. Start development server: pnpm run dev
2. Configure MCP clients to use the tsx watch command (see configs above)
3. Edit TypeScript files in src/ - changes auto-restart the server
4. Test in Cursor/Claude - tools reflect changes immediately
5. For production: Switch clients back to node dist/index.js and run pnpm run build

Testing Your MCP Server

Option 1: Direct MCP Server Usage Use the server directly with MCP clients or integrate it into other applications.

Option 2: With ADK CLI (For Client-Side Testing) While this template creates an MCP server, you can create a simple client to test it:

1. Install the ADK CLI globally:

   npm install -g @iqai/adk-cli
   

2. Create a simple agent that uses your MCP server (in a separate test directory):

   # In a test directory, create an agents/agent.ts file that connects to your MCP server
   adk run  # Test the integration
   adk web  # Web interface for testing
   

This approach is useful for testing how your MCP server tools work within the ADK ecosystem.

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