{"id":30284854,"url":"https://github.com/jhenbertgit/mcp-server-template","last_synced_at":"2025-08-16T19:35:36.625Z","repository":{"id":310008806,"uuid":"1038365534","full_name":"jhenbertgit/mcp-server-template","owner":"jhenbertgit","description":null,"archived":false,"fork":false,"pushed_at":"2025-08-15T06:13:36.000Z","size":21,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-08-15T06:19:09.396Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"TypeScript","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/jhenbertgit.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"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}},"created_at":"2025-08-15T04:12:55.000Z","updated_at":"2025-08-15T06:13:39.000Z","dependencies_parsed_at":"2025-08-15T06:19:11.626Z","dependency_job_id":"b9f6e1c6-509f-4600-a5d4-9e6731b4c16a","html_url":"https://github.com/jhenbertgit/mcp-server-template","commit_stats":null,"previous_names":["jhenbertgit/mcp-server-template"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/jhenbertgit/mcp-server-template","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jhenbertgit%2Fmcp-server-template","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jhenbertgit%2Fmcp-server-template/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jhenbertgit%2Fmcp-server-template/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jhenbertgit%2Fmcp-server-template/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/jhenbertgit","download_url":"https://codeload.github.com/jhenbertgit/mcp-server-template/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jhenbertgit%2Fmcp-server-template/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":270763337,"owners_count":24641015,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-08-16T02:00:11.002Z","response_time":91,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"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":[],"created_at":"2025-08-16T19:35:32.591Z","updated_at":"2025-08-16T19:35:36.607Z","avatar_url":"https://github.com/jhenbertgit.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Local MCP Server (Weather Tool)\n\nA Model Context Protocol (MCP) server exposing a `get_weather` tool with multiple interfaces:\n- MCP stdio protocol for MCP clients\n- HTTP/JSON API endpoints\n- Server-Sent Events (SSE) for streaming responses\n\n## Features\n\n- MCP stdio server implemented with `@modelcontextprotocol/sdk`\n- HTTP server with JSON and SSE endpoints\n- Weather tool: `get_weather` with current, hourly, and daily modes using Open‑Meteo\n- Typed validation via `zod`\n- Progress updates for long-running requests\n- Health check endpoint\n\n## Requirements\n\n- Node.js 18+ (recommended LTS)\n- pnpm (project sets `packageManager: pnpm@10.x`)\n\n## Quickstart\n\n```bash\npnpm install\npnpm dev\n```\n\nThis starts the MCP server over stdio. Use an MCP-compatible client (or the Inspector below) to connect.\n\n### Run with MCP Inspector\n\nThe repo includes a helper script to launch the server in the MCP Inspector:\n\n```bash\npnpm run server:inspect\n```\n\nNotes:\n\n- On Windows, the script sets `DANGEROUSLY_OMIT_AUTH=true` for the Inspector session only.\n- The script internally runs: `pnpm dlx @modelcontextprotocol/inspector pnpm dev`.\n\n## Tool: `get_weather`\n\nRetrieves weather for a given city.\n\n**Input schema**\n\n- `city` (string, required): City name to query (e.g., \"San Francisco\").\n- `units` (\"metric\" | \"imperial\", optional, default: \"metric\").\n- `mode` (\"current\" | \"hourly\" | \"daily\", optional, default: \"current\").\n- `days` (int, optional): Only for `daily` mode; must be 7–10 (defaults to 7 if omitted).\n- `format` (\"json\" | \"text\", optional, default: environment-dependent, see below).\n\n**Response format**\n\n- JSON by default. If `format: \"text\"` (or env var below is set), returns a single text blob containing stringified JSON for compatibility.\n\n### Examples\n\nCurrent conditions (metric):\n\n```json\n{\n  \"name\": \"get_weather\",\n  \"arguments\": { \"city\": \"Tokyo\" }\n}\n```\n\nHourly next ~24h (imperial):\n\n```json\n{\n  \"name\": \"get_weather\",\n  \"arguments\": { \"city\": \"Seattle\", \"mode\": \"hourly\", \"units\": \"imperial\" }\n}\n```\n\nDaily 7–10 days (metric):\n\n```json\n{\n  \"name\": \"get_weather\",\n  \"arguments\": { \"city\": \"Berlin\", \"mode\": \"daily\", \"days\": 7 }\n}\n```\n\n## Environment Variables\n\n- `MCP_TEXT_OUTPUT=1`\n  - Forces text output (stringified JSON) for tool responses. Useful for clients that only display text.\n\n- `PORT=5000`\n  - Port for the HTTP server (default: 5000)\n\n- `DANGEROUSLY_OMIT_AUTH=true`\n  - Only for local Inspector sessions (already set by `server:inspect` on Windows). Do not use in production.\n\n## Scripts\n\n- `pnpm dev` — Run the TypeScript server with `tsx` (`src/server.ts`).\n- `pnpm build` — Type-check and emit JS via `tsc`.\n- `pnpm run server:inspect` — Launch MCP Inspector pointed at `pnpm dev`.\n\n## HTTP Endpoints\n\n### GET /health\nHealth check endpoint. Returns `{ \"status\": \"ok\" }` when the server is running.\n\n### GET /get_weather\nGet weather data in JSON format.\n\n**Query Parameters:**\n- `city` (required): City name\n- `units`: \"metric\" (default) or \"imperial\"\n- `mode`: \"current\" (default), \"hourly\", or \"daily\"\n- `days`: Number of days (7-10, required for \"daily\" mode)\n- `format`: \"json\" (default) or \"text\"\n\n### GET /stream/get_weather\nStream weather data with Server-Sent Events (SSE). Same parameters as `/get_weather`.\n\n### POST /mcp\nMCP protocol endpoint for programmatic access.\n\n## Project Structure\n\n- `src/server.ts` — MCP and HTTP server implementation\n  - Handles MCP stdio protocol\n  - Provides HTTP/JSON and SSE endpoints\n  - Implements the weather service\n- `package.json` — Scripts and dependencies\n- `.env` — Optional environment overrides\n\n## Implementation Details\n\n- Geocoding uses Open‑Meteo Geocoding API (no API key)\n- Forecast data retrieved via `openmeteo` SDK\n- Implements MCP protocol over both stdio and HTTP\n- Provides both JSON and text response formats\n- Includes progress events for long-running requests\n- Implements CORS for web access\n- Validates all inputs with Zod\n\n### Response Formats\n\n#### Current Weather\n```json\n{\n  \"location\": \"City, Region, Country\",\n  \"latitude\": 0.0,\n  \"longitude\": 0.0,\n  \"units\": \"metric\",\n  \"mode\": \"current\",\n  \"current\": {\n    \"temperature\": 20.5,\n    \"temperature_unit\": \"°C\",\n    \"wind_speed\": 15.3,\n    \"wind_speed_unit\": \"km/h\"\n  }\n}\n```\n\n#### Hourly Forecast\n```json\n{\n  \"location\": \"City, Region, Country\",\n  \"units\": \"metric\",\n  \"mode\": \"hourly\",\n  \"hourly_next_24h\": [\n    {\n      \"time_iso\": \"2023-01-01T00:00:00.000Z\",\n      \"temperature\": 18.5,\n      \"temperature_unit\": \"°C\",\n      \"wind_speed\": 12.3,\n      \"wind_speed_unit\": \"km/h\"\n    }\n  ]\n}\n```\n\n#### Daily Forecast\n```json\n{\n  \"location\": \"City, Region, Country\",\n  \"units\": \"metric\",\n  \"mode\": \"daily\",\n  \"days\": 7,\n  \"daily\": [\n    {\n      \"date\": \"2023-01-01\",\n      \"t_max\": 22.5,\n      \"t_min\": 16.2,\n      \"temperature_unit\": \"°C\",\n      \"precipitation_sum\": 0.5,\n      \"precipitation_unit\": \"mm\",\n      \"wind_speed_10m_max\": 25.1,\n      \"wind_speed_unit\": \"km/h\"\n    }\n  ]\n}\n```\n\n### Units Supported\n- **Metric**: °C for temperature, km/h for wind speed\n- **Imperial**: °F for temperature, mph for wind speed\n\n## Build\n\n```bash\npnpm build\n```\n\n## License\n\nMIT\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjhenbertgit%2Fmcp-server-template","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjhenbertgit%2Fmcp-server-template","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjhenbertgit%2Fmcp-server-template/lists"}