# Reusable Prompt: Add a new MCP tool from `fsopenapi.json`

Use this prompt when adding a new MCP tool to this project.

---

You are working in the `fsmcp` workspace.

## Goal
Add a new MCP tool for this endpoint:
- **Endpoint path:** `<ENDPOINT_PATH>`
- **HTTP method:** `<HTTP_METHOD>`

Use `fsopenapi.json` as the source of truth for request/response schemas and constraints.

## Required implementation rules
1. **Read OpenAPI docs first**
   - Find endpoint details in `fsopenapi.json`:
     - summary/description
     - parameters (path/query/body)
     - response schema(s)
     - relevant referenced component schemas and enums
   - Use exact API field names via `JsonPropertyName`.

2. **Update endpoint constants**
   - Add a new endpoint constant/function in `FsMcp/Endpoints.cs`.
   - Follow existing style (`ApiBase`, interpolation, naming consistency).

3. **Create a new tool class**
   - Create file in `FsMcp/Tools/` named after the endpoint purpose, e.g. `RegionStoresTools.cs`.
   - Add one MCP tool method with `[McpServerTool]` and detailed `[Description]`.
   - Inject and use `FoodsharingApiClient`.
   - Always call `await _apiClient.EnsureLoginAsync();` before HTTP calls.
   - Validate input parameters where appropriate (e.g. IDs > 0).
   - Use strongly typed request/response models (`record` types).
   - Add rich per-field `[Description]` metadata on model properties.
   - Reuse existing shared models if already present (avoid duplication).

4. **Register tool in host**
   - Add `.WithTools<YourNewToolsClass>()` in `FsMcp/Program.cs`.

5. **Extend documentation**
   - Update `FsMcp/README.md` with a new section for the tool including:
     - tool name
     - endpoint + purpose
     - input parameters
     - auth behavior (`USERNAME`, `PASSWORD`, CSRF)
     - output shape highlights
     - enum/date/data-quality notes that help consumers

6. **Validate**
   - Build with:
     - `dotnet build FsMcp/FsMcp.csproj -c Debug`
   - If build fails due to pre-existing unrelated issues, clearly state that and confirm whether new files are clean.

## Style constraints
- Keep changes minimal and focused.
- Match existing C# style and naming.
- Do not add unrelated refactors.
- Preserve API payload shape; do not rename wire-level JSON fields.

## Output format expected from you
At the end, provide:
1. Short summary of what changed.
2. List of changed files.
3. Validation result.
4. Any blockers or follow-up suggestions.

## Variables to fill before running this prompt
- `<ENDPOINT_PATH>` e.g. `/api/regions/{regionId}/stores`
- `<HTTP_METHOD>` e.g. `GET`

## Example invocation
"Add a new MCP tool for `GET /api/regions/{regionId}/stores` using this reusable prompt and implement all required steps."