accuweather-mcp

• Setup
• Run
• Testing
  • Unit and integration testing
  • Mutation testing
  • MCP Inspector
  • AI chat (Claude, Cursor)
  • Docker
• Patterns and practices
  • Git
  • Spotless
  • Checkstyle
  • MCP
• MCP Registry
• Future improvements

Setup

• Define the following environment variables in your system

export ACCUWEATHER_API_KEY=replace-with-your-api-key

• Define a application-local.yaml in src/main/resources/application.yaml with the following content:

logging:
  console:
    enabled: true

• If using Cursor, add the following documentation sources:
  • Spring AI documentation
  • [Wiremock documentation][https://wiremock.org/docs/]
  • [Lombok documentation][https://projectlombok.org/features/]
  • PIT documentation
  • gradle-pitest-plugin documentation

Run

• Run with SPRING_PROFILES_ACTIVE=local ./gradlew bootRun

Testing

Note: If you enable the Java debugger, it will produce output to standard out which will trigger errors in the stdio MCP protocol.

Unit and integration testing

Unit and integration tests use mockito and wiremock. To run the tests, use:

./gradlew build

Mutation testing

This project uses PIT mutation testing via the gradle-pitest-plugin to verify that tests detect injected faults, complementing JaCoCo line coverage.

• ./gradlew pitest — run mutation tests over com.jonjam.accuweathermcp.* (excluding DTOs and the bootstrap class).
• 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.

MCP Inspector

To test with MCP Inspector, run the following from the root of the repo:

npx @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"

This was sourced from this blog.

AI chat (Claude, Cursor)

1. Add this configuration to the MCP settings:

{
  "mcpServers": {
    "accuweather-mcp": {
      "command": "PATH_TO_JAVA",
      "args": ["-jar", "ABSOLUTE_PATH_TO_REPO/build/libs/accuweather-mcp-local-snapshot.jar"],
      "env": {
        "ACCUWEATHER_API_KEY": "API_KEY"
      }
    }
  }
}

If you are using SDKMAN, command should be ~/.sdkman/candidates/java/current/bin/java

This was sourced from the MCP docs.

Example user prompt:

Use the accuweather-mcp to look up the current weather in Manchester, UK.

Docker

This project uses the Jib Gradle plugin to build a Docker image.

• Build and load the image into your local Docker daemon:

./gradlew jibDockerBuild

The default image name is jonjam/accuweather-mcp.

To use the docker image with MCP Inspector, the command looks as follows:

npx @modelcontextprotocol/inspector docker run --rm -i --env "ACCUWEATHER_API_KEY=$ACCUWEATHER_API_KEY" jonjam/accuweather-mcp:latest

Patterns and practies

More information about patterns and practises for this project can be found in AGENTS.md.

Git

This project uses semantic-release to automate versioning, changelog generation, and publishing.

Important: Commit messages that are intended to trigger a release must be prefixed according to the Conventional Commits standard. For example:

• feat: add new forecast endpoint
• fix: correct hourly forecast time calculation

Spotless

This project uses the Spotless Gradle plugin to enforce a consistent Java style.

• ./gradlew spotlessApply — format sources and fix style issues.
• ./gradlew spotlessCheck — verify formatting without changing files.

Checkstyle

Static analysis and broader code-quality checks are handled by Checkstyle using a Google-style-based configuration (with formatting delegated to Spotless):

• ./gradlew checkstyleMain — run Checkstyle over main sources.
• ./gradlew checkstyleTest — run Checkstyle over test sources.

MCP

• Tools Ensure to handle errors (i.e. validation) according to the specification

MCP Registry

This server is published to the MCP Registry.

When 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.

Future improvements

• Improve error handling in gateway classes based upon AccuWeather status codes
• Add in-memory caching for AccuWeather API calls that caches data according to expires header
• Add ability to specify desired metric (i.e. Celsius or Fahrenheit) in Tools
• End to end integration tests based on Spring AI Examples