# Skincare-MCP

## Overview

Skincare-MCP is a Model Context Protocol (MCP) server that provides AI-based skin analysis based on a selfie image URL. It accepts a URL pointing to a user-provided selfie, analyzes the image through two stages of processing, and returns comprehensive skin status, management recommendations, and therapy guidance. The server can be integrated with any MCP-compatible client—such as Claude Desktop App, Continue, Cline, and others—to enable real-time skincare diagnostics and personalized advice.

## Features

- Analyze basic skin status from a selfie (e.g., care-needed regions, estimated skin age, skin point score).
- Determine detailed skin type attributes (Dry, Oily, Pigmented, etc.) and generate a type code.
- Recommend tailored management methods (e.g., hydration routines, pore tightening toners).
- Provide detailed skin context and quantitative point scores for Pigmented, Pores, Redness, Sebum, Trouble, Wrinkle.
- Offer therapy guidance, including advantages, cautions, detailed procedure, and expected effect.
- Return a “recommend therapy” field (e.g., “Aqua Peeling”) based on the user’s skin profile.

## How It Works

Poke-MCP is built using the Model Context Protocol, which enables AI applications to access external tools and data sources in a standardized way. The server:

1. Connects to the skincareAPI to fetch skincare data
2. Exposes several tools through the MCP interface
3. Processes requests from MCP clients
4. Returns formatted skincare information

## MCP Tools

The Skincare-MCP server exposes the following primary tool:

- **get-skin-analysis**:

  - **Description**: Given a selfie image URL, returns a JSON object containing all available skin analysis fields (both basic status and detailed management/therapy information).
  - **Input Parameters**:

    - `image_url` (string): Publicly accessible URL of the user’s selfie image.

  - **Output**: JSON containing fields (listed in “Provided Fields” below).

## Provided Fields

The server returns all of the following fields (no separate “analysis_1” vs. “analysis_2” nesting is exposed to the client; they’re merged in output).

1. **need_therapy**

   - Array of face regions requiring care or therapy (e.g., `["right cheek", "jaw"]`).

2. **skin_age**

   - Integer representing the estimated skin age.

3. **skin_point**

   - `max_score` (number): Maximum possible score (e.g., 10).
   - `current_score` (number): User’s current skin point score.

4. **skin_type** (boolean flags)

   - `Dry`
   - `Non_Pigmented`
   - `Oily`
   - `Pigmented`
   - `Resistant`
   - `Sensitive`
   - `Tight`
   - `Wrinkle`

5. **skin_type_analysis.type_code**

   - A string code representing the combination of True/False flags (e.g., “OSRT”).

6. **manage_methods.recommend_methods**

   - Array of strings suggesting skin management routines (e.g., hydration, pore-tightening toner, double cleansing at night, sebum-controlling cleanser, weekly sebum care pack).

7. **skin_detail_analysis.skin_detail_context**

   - Array of descriptive keywords summarizing detailed skin condition (e.g., `["elastic skin texture", "oil and pore management needed"]`).

8. **skin_detail_analysis.skin_detail_points**

   - `Pigmented` (number)
   - `Pores` (number)
   - `Redness` (number)
   - `Sebum` (number)
   - `Trouble` (number)
   - `Wrinkle` (number)
   - `max_score` (number)

9. **therapy.all_datas**

   - `advantage` (string): Description of therapy’s main advantages.
   - `caution` (array of strings): List of post-treatment precautions.
   - `detail` (string): Detailed explanation of the procedure and mechanism.
   - `effect` (string): Expected outcome/effect on the skin.

10. **therapy.recommend_therapy**

    - A single string with the recommended therapy name (e.g., “Aqua Peeling”).

## Architecture

Skincare-MCP is built using:

- **TypeScript** (Node.js runtime)
- **@modelcontextprotocol/sdk** (MCP TypeScript SDK for tool registration and message handling)
- **Zod** (for schema validation of incoming parameters)
- **Express.js** (or similar HTTP server framework) to handle the HTTP `POST` endpoint and route requests internally
- **Internal ML Model** (Python ONNX or TensorFlow backend) to perform image-based skin analysis
- **Sharp** or **Jimp** (Node.js image processing) to fetch and pre-process images from URLs before feeding them to the ML model

### Manual Installation

```bash
# 1. Clone the repository
git clone https://github.com/leegentle/skincare-mcp.git
cd skincare-mcp

# 2. Install dependencies
npm install

# 3. Build the project
npm run build

# 4. (Optional) Run tests
npm test

# 5. Start the server
npm start
```

After starting, the server listens on a default port (e.g., `3000`) and can be invoked by an MCP client at:

```
mcp://localhost:3000/get-skin-analysis
```

## Usage

### With Claude Desktop App

1. Download and install [Claude Desktop App](https://claude.ai).
2. Open Claude Desktop settings, then go to **Developer** settings.
3. Edit your configuration file (e.g., `config.json`) to include:

   ```json
   {
     "mcpServers": {
       "skincare": {
         "command": "node path/to/skincare-mcp/build/index.js"
       }
     }
   }
   ```

4. Restart Claude Desktop.
5. You will now see a “get-skin-analysis” tool under the “skincare” server when interacting with Claude.

### Example Queries

Once connected, you can ask your MCP-capable client (e.g., Claude Desktop) to run commands like:

- “Analyze my skin: `get-skin-analysis image_url=https://example.com/selfie.jpg`”
- “What management methods should I follow for my skin?” (the client can automatically call `get-skin-analysis` behind the scenes)
- “Recommend a therapy based on my skin condition”

## Adding New Features

To extend Skincare-MCP with additional tools or analyses:

1. **Define new Zod schemas** in `src/types.ts` for any additional input parameters or output fields.
2. **Create helper functions** in `src/utils/` (e.g., data fetchers, new model inferences).
3. **Register a new tool** in `src/tools.ts` using:

   ```ts
   server.tool(
     "new-skin-tool",
     "Description of this new tool’s functionality.",
     {
       /* input parameter schema via Zod */
     },
     async (params) => {
       // Tool logic: fetch/process image, call model, return JSON
     }
   );
   ```

4. **Update `src/index.ts`** to import and include the new tool.
5. **Write unit/integration tests** under `tests/` to validate new functionality.
6. **Rebuild and restart** the server to make the new tool available to MCP clients.

## Acknowledgments

- [Model Context Protocol](https://modelcontextprotocol.io) for providing a standardized way to expose external tools to AI clients.
- Internal ML teams for developing the skin-analysis models.
- [Smithery](https://smithery.ai) for MCP deployment and discovery services.

---

**About**
Skincare-MCP is maintained by the @leegentle team. It demonstrates how to build a domain-specific MCP server—focused on skin diagnostics—that can seamlessly integrate into AI workflows and client applications.

[1]: https://github.com/NaveenBandarage/poke-mcp "GitHub - NaveenBandarage/poke-mcp: A repo to play around with MCP (Model Context Protocol) and to query the PokeDex API"