Template MCP Server

^{Template for creating MCP servers with PulseEngine}

A template repository for creating Model Context Protocol (MCP) servers using the PulseEngine MCP framework in Rust.

Note

Part of the PulseEngine toolchain. Use this template to scaffold new MCP servers with tools, resources, and authentication built in.

Getting Started

Option 1: Automated Setup (Recommended)

The fastest way to customize this template for your project:

# 1. Use this template on GitHub (click "Use this template" button)
# 2. Clone your new repository
git clone https://github.com/yourusername/your-mcp-server.git
cd your-mcp-server

# 3. Run the initialization script
./init.sh

# 4. Follow the prompts to configure your server
# The script will automatically:
#   - Replace all template placeholders
#   - Rename directories
#   - Update package.json, Cargo.toml, and all config files
#   - Validate all changes

# 5. Build and test
cargo build --release
./target/release/your-mcp-server

The initialization script takes ~2 minutes and handles all the tedious find-and-replace work automatically.

Option 2: Manual Setup

If you prefer to set up manually:

Click to expand manual setup instructions

1. Clone the template

git clone https://github.com/yourusername/your-mcp-server.git
cd your-mcp-server

2. Replace placeholders (use checklist)

Required replacements across all files:

@yourusername/template-mcp-server → your scoped package name (e.g., @mycompany/myapp-mcp-server)
template-mcp-server → your package name (e.g., myapp-mcp-server)
@yourusername → your npm scope (e.g., @mycompany)
yourusername in GitHub URLs → your GitHub username
Your Name <your.email@example.com> → your author info
Template MCP Server → your server name

Files to update:

All package.json files (npm/, platform-packages/*/)
All .js files (npm/.js, platform-packages//index.js, scripts/*.js)
Both Cargo.toml files (root and template-mcp-server/)
.github/workflows/npm-publish.yml
README.md, PUBLISHING.md, CONTRIBUTING.md

3. Rename directory

mv template-mcp-server your-package-name
# Update Cargo.toml workspace members to match

4. Validate your changes

./scripts/validate.sh

5. Build and test

cargo build
echo '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}' | ./target/debug/your-mcp-server

Quick Start After Setup

Once initialized, build and test your server:

# Build
cargo build --release

# Test tools
echo '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}' | ./target/release/your-mcp-server

# Test resources
echo '{"jsonrpc":"2.0","id":2,"method":"resources/list","params":{}}' | ./target/release/your-mcp-server

What's Included

This template provides:

Complete MCP server setup using PulseEngine MCP framework
Automatic tool & resource discovery with #[mcp_tools] and #[mcp_resource] macros
Example tools demonstrating different parameter types:
- Simple status check (no parameters)
- Echo with optional parameters
- Numeric calculations
- Structured data creation
- List processing
- Error handling examples
Example resources for read-only data access:
- Server status information (template://server-status)
- Server configuration (template://server-config)
- Parameterized data lookup (template://example-data/{id})
URI template support for parameterized resources
STDIO transport for integration with MCP clients
Proper logging configuration for debugging

Project Structure

template-mcp-server/
├── Cargo.toml                    # Workspace configuration
├── template-mcp-server/
│   ├── Cargo.toml                # Package configuration
│   ├── src/
│   │   ├── main.rs               # Server entry point
│   │   └── lib.rs                # Server implementation & tools
├── README.md                     # This file
├── LICENSE                       # MIT License
└── .github/                      # GitHub templates
    ├── ISSUE_TEMPLATE/
    ├── PULL_REQUEST_TEMPLATE.md
    └── dependabot.yml

Installation

From npm (Recommended)

Install globally to use with any MCP client:

npm install -g @yourusername/template-mcp-server

Or use directly with npx:

npx @yourusername/template-mcp-server

From Source

Prerequisites
- Rust 1.75.0 or later
- Git
- Node.js 16+ (for npm distribution)

Clone and Build

git clone https://github.com/yourusername/template-mcp-server.git
cd template-mcp-server
cargo build --release

Run the Server
```
./target/release/template-mcp-server
```

Platform-Specific Binaries

Pre-built binaries are available for:

macOS (x64, arm64)
Linux (x64, arm64)
Windows (x64)

Download from GitHub Releases

Development

Pre-commit Hooks Setup

This template includes pre-commit hooks for code quality:

# Install pre-commit (if not already installed)
pip install pre-commit

# Install the git hooks
pre-commit install

# Run manually on all files
pre-commit run --all-files

The hooks include:

Rust formatting (cargo fmt)
Rust linting (cargo clippy)
Secret detection (detect-secrets)
File checks (trailing whitespace, EOF, YAML/JSON/TOML validation)
Markdown linting
JavaScript/JSON formatting (prettier)

Building

cargo build

Running

cargo run

Testing with MCP Inspector

# Install MCP Inspector
npm install -g @modelcontextprotocol/inspector

# Test your server
npx @modelcontextprotocol/inspector ./target/debug/template-mcp-server

Testing with Direct JSON-RPC

# List available tools
echo '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}' | ./target/debug/template-mcp-server

# Call a tool
echo '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"get_status","arguments":{}}}' | ./target/debug/template-mcp-server

# List available resources
echo '{"jsonrpc":"2.0","id":3,"method":"resources/list","params":{}}' | ./target/debug/template-mcp-server

# Read a resource
echo '{"jsonrpc":"2.0","id":4,"method":"resources/read","params":{"uri":"template://server-status"}}' | ./target/debug/template-mcp-server

Tools vs Resources

This template demonstrates both MCP Tools and MCP Resources:

Tools (Operations)

Tools are functions that perform operations or modify state. They:

Take parameters as input
Can have side effects (create, update, delete)
Return results from their execution
Are called via tools/call method

Examples in template:

get_status() - Checks server status
echo(message, prefix) - Transforms input
add_numbers(a, b) - Performs calculations
create_data(...) - Creates new data

Resources (Read-Only Data)

Resources provide read-only access to data. They:

Use URI templates for identification
Cannot modify state (read-only)
Are accessed via resources/read method
Perfect for configuration, status, or reference data

Examples in template:

template://server-status - Current server status
template://server-config - Server configuration
template://example-data/{id} - Data lookup by ID

When to Use Each

Use Tools For	Use Resources For
Operations & actions	Read-only data access
Data modification	Configuration settings
Calculations	Status information
API calls	Reference data
File operations	Cached data
Dynamic processing	Static information

Customizing Your Server

1. Update Package Information

Edit template-mcp-server/Cargo.toml:

[package]
name = "your-mcp-server"
description = "Your server description"
authors = ["Your Name <your.email@example.com>"]
repository = "https://github.com/yourusername/your-mcp-server"

2. Implement Your Tools

In src/lib.rs, modify the #[mcp_tools] impl block:

#[mcp_tools]
impl YourMcpServer {
    /// Your custom tool
    pub async fn your_tool(&self, param: String) -> anyhow::Result<String> {
        // Your implementation here
        Ok(format!("Result: {}", param))
    }
}

3. Add Server State

Add fields to your server struct:

#[mcp_server(name = "Your Server")]
#[derive(Clone)]
pub struct YourMcpServer {
    data: Arc<RwLock<HashMap<String, String>>>,
    config: YourConfig,
}

4. Update Server Configuration

Modify the #[mcp_server] attributes:

#[mcp_server(
    name = "Your Amazing MCP Server",
    version = "1.0.0",
    description = "Does amazing things",
    auth = "file"  // or "memory", "disabled"
)]

Integration with MCP Clients

Claude Desktop

Using npm installation:

{
  "servers": {
    "your-server": {
      "command": "npx",
      "args": ["@yourusername/template-mcp-server"]
    }
  }
}

Using local binary:

{
  "servers": {
    "your-server": {
      "command": "/path/to/your-mcp-server",
      "args": []
    }
  }
}

Continue.dev

Using npm installation:

{
  "mcpServers": {
    "your-server": {
      "command": "npx",
      "args": ["@yourusername/template-mcp-server"]
    }
  }
}

Using local binary:

{
  "mcpServers": {
    "your-server": {
      "command": "/path/to/your-mcp-server"
    }
  }
}

Framework Features

This template uses the PulseEngine MCP framework which provides:

Automatic tool discovery - Public methods become MCP tools
Type-safe parameter handling - Automatic JSON deserialization
Error handling - Proper MCP error responses
Authentication - Optional auth with multiple backends
Transport support - STDIO, HTTP, WebSocket
Monitoring - Built-in metrics and tracing
Validation - Request/response validation

Authentication

The template includes authentication support:

auth = "disabled" - No authentication (development)
auth = "memory" - In-memory auth (testing)
auth = "file" - File-based auth (production)

For production use, configure file-based auth:

#[mcp_server(auth = "file")]

Monitoring & Debugging

The server includes comprehensive logging. Set log levels:

RUST_LOG=debug ./target/debug/template-mcp-server

Contributing

Fork the repository
Create a feature branch
Make your changes
Add tests if applicable
Submit a pull request

License

This template is licensed under the MIT License. See LICENSE for details.

Troubleshooting

Common Issues After Setup

"Found unreplaced placeholders" error

Run ./scripts/validate.sh to see which placeholders remain
Use ./init.sh to automatically fix all placeholders
Or manually search and replace the listed placeholders

Build fails with missing dependencies

Make sure you renamed the template-mcp-server directory to match your package name
Update Cargo.toml workspace members to reference the new directory name
Run cargo clean && cargo build

NPM publish fails

Verify all package.json files have matching versions
Check that platform package names match the main package's optionalDependencies
Ensure you have the correct NPM_TOKEN secret configured

Pre-commit hooks fail

Install required tools: pip install pre-commit detect-secrets
Install Rust components: rustup component add rustfmt clippy
Run pre-commit install to set up the hooks
If detect-secrets fails, update .secrets.baseline: detect-secrets scan --baseline .secrets.baseline

CI/CD workflow issues

Ensure all GitHub secrets are configured (NPM_TOKEN)
Check that workflow references use your package name, not template-mcp-server
Verify binary names in workflows match your package name

Validation

Run the validation script anytime to check for configuration issues:

./scripts/validate.sh

This will check for:

Unreplaced template placeholders
Incorrect package names
Missing author information
Broken repository URLs

Support

Template Usage

When using this template:

Click "Use this template" on GitHub
Create your repository with a descriptive name
Clone and customize as described above
Delete this section from your README
Update all placeholder information with your project details

Happy building!

_{Part of PulseEngine — formally verified WebAssembly toolchain for safety-critical systems}

Name		Name	Last commit message	Last commit date
Latest commit History 12 Commits
.github		.github
npm		npm
platform-packages		platform-packages
scripts		scripts
template-mcp-server		template-mcp-server
.gitignore		.gitignore
.markdownlint.json		.markdownlint.json
.npmignore		.npmignore
.pre-commit-config.yaml		.pre-commit-config.yaml
.secrets.baseline		.secrets.baseline
CONTRIBUTING.md		CONTRIBUTING.md
Cargo-dev.toml		Cargo-dev.toml
Cargo.toml		Cargo.toml
LICENSE		LICENSE
PUBLISHING.md		PUBLISHING.md
README.md		README.md
init.sh		init.sh
package.json		package.json
requirements-dev.txt		requirements-dev.txt

Folders and files

Latest commit

History

Repository files navigation

Template MCP Server

Getting Started

Option 1: Automated Setup (Recommended)

Option 2: Manual Setup

1. Clone the template

2. Replace placeholders (use checklist)

3. Rename directory

4. Validate your changes

5. Build and test

Quick Start After Setup

What's Included

Project Structure

Installation

From npm (Recommended)

From Source

Platform-Specific Binaries

Development

Pre-commit Hooks Setup

Building

Running

Testing with MCP Inspector

Testing with Direct JSON-RPC

Tools vs Resources

Tools (Operations)

Resources (Read-Only Data)

When to Use Each

Customizing Your Server

1. Update Package Information

2. Implement Your Tools

3. Add Server State

4. Update Server Configuration

Integration with MCP Clients

Claude Desktop

Continue.dev

Framework Features

Authentication

Monitoring & Debugging

Contributing

License

Troubleshooting

Common Issues After Setup

Validation

Support

Template Usage

About

Topics

Resources

License

Contributing

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages