{"id":47115441,"url":"https://github.com/pulseengine/template-mcp-server","last_synced_at":"2026-03-12T18:58:25.625Z","repository":{"id":309771406,"uuid":"1035890477","full_name":"pulseengine/template-mcp-server","owner":"pulseengine","description":"Template repository for creating MCP servers with the PulseEngine MCP framework","archived":false,"fork":false,"pushed_at":"2026-03-01T13:05:25.000Z","size":56,"stargazers_count":0,"open_issues_count":5,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-03-01T16:47:18.469Z","etag":null,"topics":["mcp","pulseengine","rust","template"],"latest_commit_sha":null,"homepage":"https://github.com/pulseengine/template-mcp-server","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/pulseengine.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-08-11T08:46:06.000Z","updated_at":"2026-03-01T13:05:28.000Z","dependencies_parsed_at":"2025-08-13T19:31:21.985Z","dependency_job_id":"13dbfb4d-79f3-4bdd-b897-c0c782fdbd5d","html_url":"https://github.com/pulseengine/template-mcp-server","commit_stats":null,"previous_names":["pulseengine/template-mcp-server"],"tags_count":1,"template":true,"template_full_name":null,"purl":"pkg:github/pulseengine/template-mcp-server","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pulseengine%2Ftemplate-mcp-server","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pulseengine%2Ftemplate-mcp-server/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pulseengine%2Ftemplate-mcp-server/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pulseengine%2Ftemplate-mcp-server/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/pulseengine","download_url":"https://codeload.github.com/pulseengine/template-mcp-server/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pulseengine%2Ftemplate-mcp-server/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":30439122,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-03-12T14:34:45.044Z","status":"ssl_error","status_checked_at":"2026-03-12T14:09:33.793Z","response_time":114,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["mcp","pulseengine","rust","template"],"created_at":"2026-03-12T18:58:24.827Z","updated_at":"2026-03-12T18:58:25.617Z","avatar_url":"https://github.com/pulseengine.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cdiv align=\"center\"\u003e\n\n# Template MCP Server\n\n\u003csup\u003eTemplate for creating MCP servers with PulseEngine\u003c/sup\u003e\n\n\u0026nbsp;\n\n![Rust](https://img.shields.io/badge/Rust-CE422B?style=flat-square\u0026logo=rust\u0026logoColor=white\u0026labelColor=1a1b27)\n![MCP](https://img.shields.io/badge/MCP-654FF0?style=flat-square\u0026logoColor=white\u0026labelColor=1a1b27)\n![License: MIT](https://img.shields.io/badge/License-MIT-blue?style=flat-square\u0026labelColor=1a1b27)\n\n\u003c/div\u003e\n\n\u0026nbsp;\n\nA template repository for creating Model Context Protocol (MCP) servers using the [PulseEngine MCP framework](https://github.com/pulseengine/mcp) in Rust.\n\n\u003e [!NOTE]\n\u003e Part of the PulseEngine toolchain. Use this template to scaffold new MCP servers with tools, resources, and authentication built in.\n\n## Getting Started\n\n### Option 1: Automated Setup (Recommended)\n\nThe fastest way to customize this template for your project:\n\n```bash\n# 1. Use this template on GitHub (click \"Use this template\" button)\n# 2. Clone your new repository\ngit clone https://github.com/yourusername/your-mcp-server.git\ncd your-mcp-server\n\n# 3. Run the initialization script\n./init.sh\n\n# 4. Follow the prompts to configure your server\n# The script will automatically:\n#   - Replace all template placeholders\n#   - Rename directories\n#   - Update package.json, Cargo.toml, and all config files\n#   - Validate all changes\n\n# 5. Build and test\ncargo build --release\n./target/release/your-mcp-server\n```\n\nThe initialization script takes ~2 minutes and handles all the tedious find-and-replace work automatically.\n\n### Option 2: Manual Setup\n\nIf you prefer to set up manually:\n\n\u003cdetails\u003e\n\u003csummary\u003eClick to expand manual setup instructions\u003c/summary\u003e\n\n#### 1. Clone the template\n\n```bash\ngit clone https://github.com/yourusername/your-mcp-server.git\ncd your-mcp-server\n```\n\n#### 2. Replace placeholders (use checklist)\n\n**Required replacements across all files:**\n\n- [ ] `@yourusername/template-mcp-server` → your scoped package name (e.g., `@mycompany/myapp-mcp-server`)\n- [ ] `template-mcp-server` → your package name (e.g., `myapp-mcp-server`)\n- [ ] `@yourusername` → your npm scope (e.g., `@mycompany`)\n- [ ] `yourusername` in GitHub URLs → your GitHub username\n- [ ] `Your Name \u003cyour.email@example.com\u003e` → your author info\n- [ ] `Template MCP Server` → your server name\n\n**Files to update:**\n\n- All `package.json` files (npm/, platform-packages/\\*/)\n- All `.js` files (npm/_.js, platform-packages/_/index.js, scripts/\\*.js)\n- Both `Cargo.toml` files (root and template-mcp-server/)\n- `.github/workflows/npm-publish.yml`\n- `README.md`, `PUBLISHING.md`, `CONTRIBUTING.md`\n\n#### 3. Rename directory\n\n```bash\nmv template-mcp-server your-package-name\n# Update Cargo.toml workspace members to match\n```\n\n#### 4. Validate your changes\n\n```bash\n./scripts/validate.sh\n```\n\n#### 5. Build and test\n\n```bash\ncargo build\necho '{\"jsonrpc\":\"2.0\",\"id\":1,\"method\":\"tools/list\",\"params\":{}}' | ./target/debug/your-mcp-server\n```\n\n\u003c/details\u003e\n\n### Quick Start After Setup\n\nOnce initialized, build and test your server:\n\n```bash\n# Build\ncargo build --release\n\n# Test tools\necho '{\"jsonrpc\":\"2.0\",\"id\":1,\"method\":\"tools/list\",\"params\":{}}' | ./target/release/your-mcp-server\n\n# Test resources\necho '{\"jsonrpc\":\"2.0\",\"id\":2,\"method\":\"resources/list\",\"params\":{}}' | ./target/release/your-mcp-server\n```\n\n## What's Included\n\nThis template provides:\n\n- **Complete MCP server setup** using PulseEngine MCP framework\n- **Automatic tool \u0026 resource discovery** with `#[mcp_tools]` and `#[mcp_resource]` macros\n- **Example tools** demonstrating different parameter types:\n  - Simple status check (no parameters)\n  - Echo with optional parameters\n  - Numeric calculations\n  - Structured data creation\n  - List processing\n  - Error handling examples\n- **Example resources** for read-only data access:\n  - Server status information (`template://server-status`)\n  - Server configuration (`template://server-config`)\n  - Parameterized data lookup (`template://example-data/{id}`)\n- **URI template support** for parameterized resources\n- **STDIO transport** for integration with MCP clients\n- **Proper logging configuration** for debugging\n\n## Project Structure\n\n```\ntemplate-mcp-server/\n├── Cargo.toml                    # Workspace configuration\n├── template-mcp-server/\n│   ├── Cargo.toml                # Package configuration\n│   ├── src/\n│   │   ├── main.rs               # Server entry point\n│   │   └── lib.rs                # Server implementation \u0026 tools\n├── README.md                     # This file\n├── LICENSE                       # MIT License\n└── .github/                      # GitHub templates\n    ├── ISSUE_TEMPLATE/\n    ├── PULL_REQUEST_TEMPLATE.md\n    └── dependabot.yml\n```\n\n## Installation\n\n### From npm (Recommended)\n\nInstall globally to use with any MCP client:\n\n```bash\nnpm install -g @yourusername/template-mcp-server\n```\n\nOr use directly with npx:\n\n```bash\nnpx @yourusername/template-mcp-server\n```\n\n### From Source\n\n1. **Prerequisites**\n\n   - Rust 1.75.0 or later\n   - Git\n   - Node.js 16+ (for npm distribution)\n\n2. **Clone and Build**\n\n   ```bash\n   git clone https://github.com/yourusername/template-mcp-server.git\n   cd template-mcp-server\n   cargo build --release\n   ```\n\n3. **Run the Server**\n\n   ```bash\n   ./target/release/template-mcp-server\n   ```\n\n### Platform-Specific Binaries\n\nPre-built binaries are available for:\n\n- macOS (x64, arm64)\n- Linux (x64, arm64)\n- Windows (x64)\n\nDownload from [GitHub Releases](https://github.com/yourusername/template-mcp-server/releases)\n\n## Development\n\n### Pre-commit Hooks Setup\n\nThis template includes pre-commit hooks for code quality:\n\n```bash\n# Install pre-commit (if not already installed)\npip install pre-commit\n\n# Install the git hooks\npre-commit install\n\n# Run manually on all files\npre-commit run --all-files\n```\n\nThe hooks include:\n\n- **Rust formatting** (cargo fmt)\n- **Rust linting** (cargo clippy)\n- **Secret detection** (detect-secrets)\n- **File checks** (trailing whitespace, EOF, YAML/JSON/TOML validation)\n- **Markdown linting**\n- **JavaScript/JSON formatting** (prettier)\n\n### Building\n\n```bash\ncargo build\n```\n\n### Running\n\n```bash\ncargo run\n```\n\n### Testing with MCP Inspector\n\n```bash\n# Install MCP Inspector\nnpm install -g @modelcontextprotocol/inspector\n\n# Test your server\nnpx @modelcontextprotocol/inspector ./target/debug/template-mcp-server\n```\n\n### Testing with Direct JSON-RPC\n\n```bash\n# List available tools\necho '{\"jsonrpc\":\"2.0\",\"id\":1,\"method\":\"tools/list\",\"params\":{}}' | ./target/debug/template-mcp-server\n\n# Call a tool\necho '{\"jsonrpc\":\"2.0\",\"id\":2,\"method\":\"tools/call\",\"params\":{\"name\":\"get_status\",\"arguments\":{}}}' | ./target/debug/template-mcp-server\n\n# List available resources\necho '{\"jsonrpc\":\"2.0\",\"id\":3,\"method\":\"resources/list\",\"params\":{}}' | ./target/debug/template-mcp-server\n\n# Read a resource\necho '{\"jsonrpc\":\"2.0\",\"id\":4,\"method\":\"resources/read\",\"params\":{\"uri\":\"template://server-status\"}}' | ./target/debug/template-mcp-server\n```\n\n## Tools vs Resources\n\nThis template demonstrates both **MCP Tools** and **MCP Resources**:\n\n### Tools (Operations)\n\nTools are functions that **perform operations** or **modify state**. They:\n\n- Take parameters as input\n- Can have side effects (create, update, delete)\n- Return results from their execution\n- Are called via `tools/call` method\n\n**Examples in template:**\n\n- `get_status()` - Checks server status\n- `echo(message, prefix)` - Transforms input\n- `add_numbers(a, b)` - Performs calculations\n- `create_data(...)` - Creates new data\n\n### Resources (Read-Only Data)\n\nResources provide **read-only access to data**. They:\n\n- Use URI templates for identification\n- Cannot modify state (read-only)\n- Are accessed via `resources/read` method\n- Perfect for configuration, status, or reference data\n\n**Examples in template:**\n\n- `template://server-status` - Current server status\n- `template://server-config` - Server configuration\n- `template://example-data/{id}` - Data lookup by ID\n\n### When to Use Each\n\n| Use Tools For        | Use Resources For      |\n| -------------------- | ---------------------- |\n| Operations \u0026 actions | Read-only data access  |\n| Data modification    | Configuration settings |\n| Calculations         | Status information     |\n| API calls            | Reference data         |\n| File operations      | Cached data            |\n| Dynamic processing   | Static information     |\n\n## Customizing Your Server\n\n### 1. Update Package Information\n\nEdit `template-mcp-server/Cargo.toml`:\n\n```toml\n[package]\nname = \"your-mcp-server\"\ndescription = \"Your server description\"\nauthors = [\"Your Name \u003cyour.email@example.com\u003e\"]\nrepository = \"https://github.com/yourusername/your-mcp-server\"\n```\n\n### 2. Implement Your Tools\n\nIn `src/lib.rs`, modify the `#[mcp_tools]` impl block:\n\n```rust\n#[mcp_tools]\nimpl YourMcpServer {\n    /// Your custom tool\n    pub async fn your_tool(\u0026self, param: String) -\u003e anyhow::Result\u003cString\u003e {\n        // Your implementation here\n        Ok(format!(\"Result: {}\", param))\n    }\n}\n```\n\n### 3. Add Server State\n\nAdd fields to your server struct:\n\n```rust\n#[mcp_server(name = \"Your Server\")]\n#[derive(Clone)]\npub struct YourMcpServer {\n    data: Arc\u003cRwLock\u003cHashMap\u003cString, String\u003e\u003e\u003e,\n    config: YourConfig,\n}\n```\n\n### 4. Update Server Configuration\n\nModify the `#[mcp_server]` attributes:\n\n```rust\n#[mcp_server(\n    name = \"Your Amazing MCP Server\",\n    version = \"1.0.0\",\n    description = \"Does amazing things\",\n    auth = \"file\"  // or \"memory\", \"disabled\"\n)]\n```\n\n## Integration with MCP Clients\n\n### Claude Desktop\n\nUsing npm installation:\n\n```json\n{\n  \"servers\": {\n    \"your-server\": {\n      \"command\": \"npx\",\n      \"args\": [\"@yourusername/template-mcp-server\"]\n    }\n  }\n}\n```\n\nUsing local binary:\n\n```json\n{\n  \"servers\": {\n    \"your-server\": {\n      \"command\": \"/path/to/your-mcp-server\",\n      \"args\": []\n    }\n  }\n}\n```\n\n### Continue.dev\n\nUsing npm installation:\n\n```json\n{\n  \"mcpServers\": {\n    \"your-server\": {\n      \"command\": \"npx\",\n      \"args\": [\"@yourusername/template-mcp-server\"]\n    }\n  }\n}\n```\n\nUsing local binary:\n\n```json\n{\n  \"mcpServers\": {\n    \"your-server\": {\n      \"command\": \"/path/to/your-mcp-server\"\n    }\n  }\n}\n```\n\n## Framework Features\n\nThis template uses the PulseEngine MCP framework which provides:\n\n- **Automatic tool discovery** - Public methods become MCP tools\n- **Type-safe parameter handling** - Automatic JSON deserialization\n- **Error handling** - Proper MCP error responses\n- **Authentication** - Optional auth with multiple backends\n- **Transport support** - STDIO, HTTP, WebSocket\n- **Monitoring** - Built-in metrics and tracing\n- **Validation** - Request/response validation\n\n## Authentication\n\nThe template includes authentication support:\n\n- `auth = \"disabled\"` - No authentication (development)\n- `auth = \"memory\"` - In-memory auth (testing)\n- `auth = \"file\"` - File-based auth (production)\n\nFor production use, configure file-based auth:\n\n```rust\n#[mcp_server(auth = \"file\")]\n```\n\n## Monitoring \u0026 Debugging\n\nThe server includes comprehensive logging. Set log levels:\n\n```bash\nRUST_LOG=debug ./target/debug/template-mcp-server\n```\n\n## Contributing\n\n1. Fork the repository\n2. Create a feature branch\n3. Make your changes\n4. Add tests if applicable\n5. Submit a pull request\n\n## License\n\nThis template is licensed under the MIT License. See [LICENSE](LICENSE) for details.\n\n## Troubleshooting\n\n### Common Issues After Setup\n\n**\"Found unreplaced placeholders\" error**\n\n- Run `./scripts/validate.sh` to see which placeholders remain\n- Use `./init.sh` to automatically fix all placeholders\n- Or manually search and replace the listed placeholders\n\n**Build fails with missing dependencies**\n\n- Make sure you renamed the `template-mcp-server` directory to match your package name\n- Update `Cargo.toml` workspace members to reference the new directory name\n- Run `cargo clean \u0026\u0026 cargo build`\n\n**NPM publish fails**\n\n- Verify all `package.json` files have matching versions\n- Check that platform package names match the main package's `optionalDependencies`\n- Ensure you have the correct NPM_TOKEN secret configured\n\n**Pre-commit hooks fail**\n\n- Install required tools: `pip install pre-commit detect-secrets`\n- Install Rust components: `rustup component add rustfmt clippy`\n- Run `pre-commit install` to set up the hooks\n- If detect-secrets fails, update `.secrets.baseline`: `detect-secrets scan --baseline .secrets.baseline`\n\n**CI/CD workflow issues**\n\n- Ensure all GitHub secrets are configured (NPM_TOKEN)\n- Check that workflow references use your package name, not `template-mcp-server`\n- Verify binary names in workflows match your package name\n\n### Validation\n\nRun the validation script anytime to check for configuration issues:\n\n```bash\n./scripts/validate.sh\n```\n\nThis will check for:\n\n- Unreplaced template placeholders\n- Incorrect package names\n- Missing author information\n- Broken repository URLs\n\n## Support\n\n- [PulseEngine MCP Documentation](https://docs.rs/pulseengine-mcp-protocol)\n- [MCP Specification](https://modelcontextprotocol.io/specification/2025-06-18)\n- [GitHub Issues](https://github.com/yourusername/your-mcp-server/issues)\n\n## Template Usage\n\nWhen using this template:\n\n1. **Click \"Use this template\"** on GitHub\n2. **Create your repository** with a descriptive name\n3. **Clone and customize** as described above\n4. **Delete this section** from your README\n5. **Update all placeholder information** with your project details\n\nHappy building!\n\n---\n\n\u003cdiv align=\"center\"\u003e\n\n\u003csub\u003ePart of \u003ca href=\"https://github.com/pulseengine\"\u003ePulseEngine\u003c/a\u003e \u0026mdash; formally verified WebAssembly toolchain for safety-critical systems\u003c/sub\u003e\n\n\u003c/div\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpulseengine%2Ftemplate-mcp-server","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fpulseengine%2Ftemplate-mcp-server","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpulseengine%2Ftemplate-mcp-server/lists"}