{
  "markdown": "\n\n# accuweather-mcp\n\n- [Setup](#setup)\n- [Run](#run)\n- [Testing](#testing)\n  - [Unit and integration testing](#unit-and-integration-testing)\n  - [Mutation testing](#mutation-testing)\n  - [MCP Inspector](#mcp-inspector)\n  - [AI chat (Claude, Cursor)](#ai-chat-claude-cursor)\n  - [Docker](#docker)\n- [Patterns and practices](#patterns-and-practies)\n  - [Git](#git)\n  - [Spotless](#spotless)\n  - [Checkstyle](#checkstyle)\n  - [MCP](#mcp)\n- [MCP Registry](#mcp-registry)\n- [Future improvements](#future-improvements)\n\n\n## Setup\n\n- Define the following environment variables in your system\n```\nexport ACCUWEATHER_API_KEY=replace-with-your-api-key\n```\n\n- Define a `application-local.yaml` in `src/main/resources/application.yaml` with the following content:\n\n```YAML\nlogging:\n  console:\n    enabled: true\n```\n\n- If using Cursor, add the following documentation sources:\n  - [Spring AI documentation](https://docs.spring.io/spring-ai/reference/)\n  - [Wiremock documentation][[https://wiremock.org/docs/]](https://wiremock.org/docs/]) \n  - [Lombok documentation][[https://projectlombok.org/features/]](https://projectlombok.org/features/]) \n  - [PIT documentation](https://pitest.org/)\n  - [gradle-pitest-plugin documentation](https://gradle-pitest-plugin.solidsoft.info/)\n\n## Run\n\n- Run with `SPRING_PROFILES_ACTIVE=local ./gradlew bootRun`\n\n## Testing\n**Note**: If you enable the Java debugger, it will produce output to standard out which will trigger errors in the stdio MCP protocol.\n\n### Unit and integration testing\nUnit and integration tests use [mockito](https://site.mockito.org/) and [wiremock](https://wiremock.org/). To run the tests, use:\n\n```bash\n./gradlew build\n```\n\n### Mutation testing\nThis project uses [PIT](https://pitest.org/) mutation testing via the [gradle-pitest-plugin](https://gradle-pitest-plugin.solidsoft.info/) to verify that tests detect injected faults, complementing JaCoCo line coverage.\n\n- `./gradlew pitest` — run mutation tests over `com.jonjam.accuweathermcp.*` (excluding DTOs and the bootstrap class).\n- Open `build/reports/pitest/index.html` to review results. Surviving mutants indicate code that is executed by tests but where a fault would not be caught.\n\n\n### MCP Inspector\n\nTo test with [MCP Inspector]([https://modelcontextprotocol.io/docs/tools/inspector](https://modelcontextprotocol.io/docs/tools/inspector)), run the following from the root of the repo:\n\n```bash\nnpx @modelcontextprotocol/inspector -e 'JAVA_TOOL_OPTIONS=-agentlib:jdwp=transport=dt_socket,server=y,suspend=n,address=*:5005' java -jar \"build/libs/accuweather-mcp-local-snapshot.jar\"\n```\n\nThis was sourced from this [blog.](https://medium.com/@tsteidle/creating-an-mcp-server-with-spring-boot-setup-debugging-and-unit-testing-8edbac9da5a6)\n\n### AI chat (Claude, Cursor)\n\n1. Add this configuration to the MCP settings:\n\n```json\n{\n  \"mcpServers\": {\n    \"accuweather-mcp\": {\n      \"command\": \"PATH_TO_JAVA\",\n      \"args\": [\"-jar\", \"ABSOLUTE_PATH_TO_REPO/build/libs/accuweather-mcp-local-snapshot.jar\"],\n      \"env\": {\n        \"ACCUWEATHER_API_KEY\": \"API_KEY\"\n      }\n    }\n  }\n}\n```\n\nIf you are using SDKMAN, `command` should be `~/.sdkman/candidates/java/current/bin/java`\n\nThis was sourced from the [MCP docs](https://modelcontextprotocol.io/docs/develop/build-server#testing-your-server-with-claude-for-desktop-3).\n\nExample user prompt:\n\n```\nUse the accuweather-mcp to look up the current weather in Manchester, UK.\n```\n\n### Docker\n\nThis project uses the [Jib Gradle plugin](https://github.com/GoogleContainerTools/jib) to build a Docker image.\n\n- Build and load the image into your local Docker daemon:\n\n```bash\n./gradlew jibDockerBuild\n```\n\nThe default image name is `jonjam/accuweather-mcp`.\n\nTo use the docker image with MCP Inspector, the command looks as follows:\n\n```bash\nnpx @modelcontextprotocol/inspector docker run --rm -i --env \"ACCUWEATHER_API_KEY=$ACCUWEATHER_API_KEY\" jonjam/accuweather-mcp:latest\n```\n\n## Patterns and practies\nMore information about patterns and practises for this project can be found in AGENTS.md.\n\n### Git\n\nThis project uses [semantic-release](https://semantic-release.gitbook.io/semantic-release) to automate versioning, changelog generation, and publishing. \n\n**Important:** Commit messages that are intended to trigger a release must be prefixed according to the [Conventional Commits](https://semantic-release.gitbook.io/semantic-release#commit-message-format) standard. For example:\n\n- `feat: add new forecast endpoint`\n- `fix: correct hourly forecast time calculation`\n\n### Spotless\n\nThis project uses the Spotless Gradle plugin to enforce a consistent Java style.\n\n- `./gradlew spotlessApply` — format sources and fix style issues.\n- `./gradlew spotlessCheck` — verify formatting without changing files.\n\n### Checkstyle\n\nStatic analysis and broader code-quality checks are handled by Checkstyle using a Google-style-based configuration (with formatting delegated to Spotless):\n\n- `./gradlew checkstyleMain` — run Checkstyle over main sources.\n- `./gradlew checkstyleTest` — run Checkstyle over test sources.\n\n### MCP\n- **Tools** Ensure to handle errors (i.e. validation) according to the [specification](https://modelcontextprotocol.io/specification/2025-11-25/server/tools#error-handling)\n\n## MCP Registry\n\nThis server is published to the [MCP Registry](https://modelcontextprotocol.io/registry). \n\nWhen using an MCP client that supports the registry (e.g. Cursor, Claude Desktop), you can add `io.github.jonjam/accuweather-mcp` from the registry and configure your AccuWeather API key as the `ACCUWEATHER_API_KEY` environment variable.\n\n## Future improvements\n- Improve error handling in gateway classes based upon [AccuWeather status codes](https://developer.accuweather.com/documentation/http-status-codes)\n- Add in-memory caching for AccuWeather API calls that caches data according to [expires header](https://developer.accuweather.com/documentation/best-practices#use-the-expires-header)\n- Add ability to specify desired metric (i.e. Celsius or Fahrenheit) in Tools\n- End to end integration tests based on [Spring AI Examples](https://github.com/spring-projects/spring-ai-examples/tree/main/integration-testing)",
  "bytes": 6171,
  "sha": "48f7ae5e46fd3df9d38038df54da20638ed3bfdfdfd9ad4482035f197a32ebcc",
  "repo_slug": "jonjam/accuweather-mcp",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_jonjam_accuweather_mcp_34463f41/readme"
}