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 f

... View full README on GitHub