mcp -birdstats

This MCP server exposes BirdWeather and eBird analysis context as read-only tools for code-execution and chat clients. The available tools are get_system_prompt, get_birdweather_api, get_ebird_api, and the check-bird prompt. By default, tool calls operate in a lightweight mode (mode=summary). If a client needs full payload access, it can request mode=full with confirmLargePayload=true. Tool responses are designed to be structured errors when something goes wrong, helping clients diagnose and recover gracefully. You can run the server via Docker as shown in the installation steps, then interact with the MCP interface over stdio or the streamable HTTP transport as configured in your environment.

Prerequisites:

• Docker (for the docker-based run) or Node.js 18+ with npm (for local builds). If you prefer running without Docker, you can build and run the Node.js server locally.

Option A — Docker (recommended):

1. Build the image (optional if using a prebuilt image): docker build -t mcp-server-birdstats .
2. Run in stdio mode (default): docker run --rm -it mcp-server-birdstats
3. Run in streamable HTTP mode (example): docker run --rm -p 3000:3000
   -e MCP_TRANSPORT=streamable-http
   -e MCP_HTTP_HOST=0.0.0.0
   -e MCP_HTTP_PORT=3000
   -e MCP_HTTP_PATH=/mcp
   mcp-server-birdstats

Option B — Local Node.js (if you prefer not to use Docker):

1. Prerequisites: Node.js 18+ and npm installed.
2. Install dependencies: npm install
3. Build (if a build step is required by the project): npm run build
4. Start the server (stdio default): npm run start
5. Start the server with streamable HTTP transport (example): MCP_TRANSPORT=streamable-http MCP_HTTP_HOST=127.0.0.1 MCP_HTTP_PORT=3000 MCP_HTTP_PATH=/mcp npm run start

Note: The README for this project provides the exact commands for build and run. The Docker path above mirrors the Docker setup described in the project documentation.

Environment variables you may encounter or configure:

• MCP_TRANSPORT: transport type (stdio, streamable-http)
• MCP_HTTP_HOST, MCP_HTTP_PORT, MCP_HTTP_PATH: settings when using HTTP transport
• MCP_ALLOWED_ORIGINS: comma-separated list of origins allowed to access the HTTP server (enables 403 on disallowed origins) Common issues:
• If using streamable-http, ensure the host/port/path are reachable by clients.
• When requesting full payloads, supply mode=full and confirmLargePayload=true to avoid token-bloat in responses.
• If you modify snapshots for BirdWeather or eBird APIs, ensure the local OpenAPI JSON files (birdweather_api.json, ebird_api.json) remain consistent with the tools’ expectations.

Tool behavior notes:

• Tools are read-only by design. They provide system prompts, API access, and search/analyze capabilities to support code execution and chat tasks without side effects.