@mrfentmen/skincare-ingredient-stack-check-mcp 0.0.0-stage → 1.0.0

package/README.md

@@ -1,3 +1,96 @@
-# Temporary Holding Version
+# Skincare Ingredient Stack Audit
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Audit a skincare routine for active-ingredient overlap, missing steps, duplicate products and shelf-life risk. Real local JSON analysis, 25 MCP tools, no paywall.
+
+## Install
+
+```bash
+npm install -g @mrfentmen/skincare-ingredient-stack-check-mcp
+```
+
+## Use with an MCP client
+
+```json
+{
+  "mcpServers": {
+    "skincare-ingredient-stack-check-mcp": {
+      "command": "npx",
+      "args": ["-y", "@mrfentmen/skincare-ingredient-stack-check-mcp"]
+    }
+  }
+}
+```
+
+## Input
+
+Pass an array, an object with an `items` array, or a JSON file path. Every item needs a name and category. Cost, quantity, dates, condition, tags and notes are optional.
+
+```json
+{
+  "items": [
+    {
+      "id": "skin-cleanser",
+      "name": "Gentle gel cleanser",
+      "category": "cleanser",
+      "tags": [
+        "gentle"
+      ],
+      "cost": 18,
+      "quantity": 1,
+      "acquired": "2026-05-01",
+      "expires": "2027-05-01",
+      "condition": "good"
+    },
+    {
+      "id": "skin-retinol",
+      "name": "Retinol serum",
+      "category": "treatment",
+      "tags": [
+        "retinol"
+      ],
+      "cost": 40,
+      "quantity": 1,
+      "acquired": "2026-08-01",
+      "expires": "2027-02-01",
+      "condition": "good"
+    }
+  ]
+}
+```
+
+## Tools (25)
+
+| Tool | What it does |
+| --- | --- |
+| `inventory_ingredient_stack` | Count items by category and show spend, quantity, freshness and the primary metric. |
+| `score_ingredient_stack_readiness` | Score readiness from 0 to 100 with coverage, condition, data and metric components. |
+| `audit_ingredient_stack_coverage` | Show category coverage ratios and unknown categories. |
+| `flag_ingredient_stack_gaps` | List missing categories, expired items, expiring items and dependency gaps. |
+| `rank_ingredient_stack_risks` | Rank coverage, expiry, budget, duplicate, condition and data risks. |
+| `check_ingredient_stack_constraints` | Check item cap, budget, coverage, expiry and metric targets. |
+| `compare_ingredient_stack_baseline` | Compare category counts with the configured baseline. |
+| `estimate_ingredient_stack_active_overlap` | Calculate the primary metric for every item with mean and pass count. |
+| `find_ingredient_stack_quick_wins` | Find low-effort fixes from small gaps, missing data, expiry and duplicates. |
+| `map_ingredient_stack_dependencies` | Map dependency groups and show which ones are missing. |
+| `test_ingredient_stack_edge_cases` | Test empty, single-item, duplicate-id, zero-cost, expiry and unknown-category cases. |
+| `summarize_ingredient_stack_findings` | Summarize counts, top gaps, top risks and data issues. |
+| `prioritize_ingredient_stack_fixes` | Rank fixes by impact divided by effort. |
+| `validate_ingredient_stack_inputs` | Validate arbitrary JSON and report schema errors and warnings. |
+| `detect_ingredient_stack_duplicates` | Group items with the same category and normalized name. |
+| `measure_ingredient_stack_variance` | Measure metric spread, category variance and tag diversity. |
+| `benchmark_ingredient_stack_options` | Benchmark lean, balanced and full sizes against readiness and data targets. |
+| `explain_ingredient_stack_tradeoffs` | Explain size, cost, freshness and data-quality tradeoffs. |
+| `draft_ingredient_stack_checklist` | Draft a checklist from gaps, high risks, missing data and budget. |
+| `export_ingredient_stack_audit` | Export the full audit with metrics, gaps, risks, constraints and next steps. |
+| `track_ingredient_stack_changes` | Compare two snapshots by item id and list added, removed and changed items. |
+| `review_ingredient_stack_history` | Review dated snapshots and show readiness, cost and metric trends. |
+| `score_ingredient_stack_confidence` | Score trust from data completeness, item count and field coverage. |
+| `recommend_ingredient_stack_next_steps` | Recommend the next five actions with quick wins. |
+| `open_ingredient_stack_questions` | List open questions that block a better audit. |
+
+## Rules
+
+- Local computation only. No network calls, no telemetry, no paywall.
+- Missing dates, costs and quantities are reported, not invented.
+- Dates use `YYYY-MM-DD`.
+- MIT licence.

package/dist/config.d.ts

@@ -0,0 +1,2 @@
+import type { ServerConfig } from "./engine.js";
+export declare const config: ServerConfig;

package/dist/config.js

@@ -0,0 +1,170 @@
+export const config = {
+    "name": "skincare-ingredient-stack-check-mcp",
+    "title": "Skincare Ingredient Stack Audit",
+    "description": "Audit a skincare routine for active-ingredient overlap, missing steps, duplicate products and shelf-life risk. Real local JSON analysis, 25 MCP tools, no paywall.",
+    "prefix": "ingredient_stack",
+    "entity": "skincare product",
+    "categories": [
+        {
+            "id": "cleanser",
+            "label": "Cleansers",
+            "baseline": 2
+        },
+        {
+            "id": "treatment",
+            "label": "Treatments",
+            "baseline": 3
+        },
+        {
+            "id": "moisturizer",
+            "label": "Moisturizers",
+            "baseline": 2
+        },
+        {
+            "id": "spf",
+            "label": "SPF",
+            "baseline": 2
+        },
+        {
+            "id": "tool",
+            "label": "Tools",
+            "baseline": 1
+        }
+    ],
+    "metric": {
+        "id": "active_overlap",
+        "label": "Active overlap",
+        "unit": "duplicate tags",
+        "target": 0,
+        "direction": "lower"
+    },
+    "target": {
+        "maxItems": 20,
+        "budget": 500,
+        "coverage": 0.8,
+        "expiryDays": 60
+    },
+    "dependencies": [
+        {
+            "id": "cleanse",
+            "label": "Cleansing step",
+            "categories": [
+                "cleanser"
+            ]
+        },
+        {
+            "id": "treat",
+            "label": "Treatment step",
+            "categories": [
+                "treatment"
+            ]
+        },
+        {
+            "id": "moisturize",
+            "label": "Moisturizing step",
+            "categories": [
+                "moisturizer"
+            ]
+        },
+        {
+            "id": "protect",
+            "label": "Sun protection",
+            "categories": [
+                "spf"
+            ]
+        }
+    ],
+    "sample": [
+        {
+            "id": "skin-cleanser",
+            "name": "Gentle gel cleanser",
+            "category": "cleanser",
+            "tags": [
+                "gentle"
+            ],
+            "cost": 18,
+            "quantity": 1,
+            "acquired": "2026-05-01",
+            "expires": "2027-05-01",
+            "condition": "good"
+        },
+        {
+            "id": "skin-retinol",
+            "name": "Retinol serum",
+            "category": "treatment",
+            "tags": [
+                "retinol"
+            ],
+            "cost": 40,
+            "quantity": 1,
+            "acquired": "2026-08-01",
+            "expires": "2027-02-01",
+            "condition": "good"
+        },
+        {
+            "id": "skin-vitc",
+            "name": "Vitamin C serum",
+            "category": "treatment",
+            "tags": [
+                "vitamin-c"
+            ],
+            "cost": 35,
+            "quantity": 1,
+            "acquired": "2026-09-01",
+            "expires": "2027-03-01",
+            "condition": "good"
+        },
+        {
+            "id": "skin-niacinamide",
+            "name": "Niacinamide serum",
+            "category": "treatment",
+            "tags": [
+                "niacinamide"
+            ],
+            "cost": 22,
+            "quantity": 1,
+            "acquired": "2026-07-01",
+            "expires": "2027-01-01",
+            "condition": "good"
+        },
+        {
+            "id": "skin-moisturizer",
+            "name": "Ceramide cream",
+            "category": "moisturizer",
+            "tags": [
+                "ceramide"
+            ],
+            "cost": 28,
+            "quantity": 1,
+            "acquired": "2026-06-01",
+            "expires": "2027-06-01",
+            "condition": "good"
+        },
+        {
+            "id": "skin-spf",
+            "name": "Mineral SPF 50",
+            "category": "spf",
+            "tags": [
+                "spf"
+            ],
+            "cost": 24,
+            "quantity": 1,
+            "acquired": "2026-05-01",
+            "expires": "2027-05-01",
+            "condition": "good"
+        },
+        {
+            "id": "skin-retinol-night",
+            "name": "Retinol night cream",
+            "category": "treatment",
+            "tags": [
+                "retinol"
+            ],
+            "cost": 38,
+            "quantity": 1,
+            "acquired": "2026-04-01",
+            "expires": "2026-12-01",
+            "condition": "fair"
+        }
+    ]
+};

package/dist/engine.d.ts

@@ -0,0 +1,270 @@
+import { z } from "zod";
+export declare const CONDITIONS: readonly ["new", "good", "fair", "worn"];
+export type Condition = (typeof CONDITIONS)[number];
+export interface CategoryConfig {
+    id: string;
+    label: string;
+    baseline: number;
+}
+export interface MetricConfig {
+    id: string;
+    label: string;
+    unit: string;
+    target: number;
+    direction: "lower" | "higher";
+}
+export interface DependencyGroup {
+    id: string;
+    label: string;
+    categories: string[];
+}
+export interface ServerConfig {
+    name: string;
+    title: string;
+    description: string;
+    prefix: string;
+    entity: string;
+    categories: CategoryConfig[];
+    metric: MetricConfig;
+    target: {
+        maxItems: number;
+        budget: number | null;
+        coverage: number;
+        expiryDays: number;
+    };
+    dependencies: DependencyGroup[];
+    sample: RawItem[];
+}
+export declare const itemSchema: z.ZodObject<{
+    id: z.ZodOptional<z.ZodString>;
+    name: z.ZodString;
+    category: z.ZodString;
+    tags: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+    cost: z.ZodOptional<z.ZodNumber>;
+    quantity: z.ZodOptional<z.ZodNumber>;
+    acquired: z.ZodOptional<z.ZodString>;
+    expires: z.ZodOptional<z.ZodString>;
+    lastUsed: z.ZodOptional<z.ZodString>;
+    condition: z.ZodOptional<z.ZodEnum<["new", "good", "fair", "worn"]>>;
+    notes: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    name: string;
+    category: string;
+    id?: string | undefined;
+    tags?: string[] | undefined;
+    cost?: number | undefined;
+    quantity?: number | undefined;
+    acquired?: string | undefined;
+    expires?: string | undefined;
+    lastUsed?: string | undefined;
+    condition?: "new" | "good" | "fair" | "worn" | undefined;
+    notes?: string | undefined;
+}, {
+    name: string;
+    category: string;
+    id?: string | undefined;
+    tags?: string[] | undefined;
+    cost?: number | undefined;
+    quantity?: number | undefined;
+    acquired?: string | undefined;
+    expires?: string | undefined;
+    lastUsed?: string | undefined;
+    condition?: "new" | "good" | "fair" | "worn" | undefined;
+    notes?: string | undefined;
+}>;
+export type RawItem = z.infer<typeof itemSchema>;
+export declare const targetSchema: z.ZodObject<{
+    maxItems: z.ZodOptional<z.ZodNumber>;
+    budget: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+    coverage: z.ZodOptional<z.ZodNumber>;
+    expiryDays: z.ZodOptional<z.ZodNumber>;
+}, "strip", z.ZodTypeAny, {
+    maxItems?: number | undefined;
+    budget?: number | null | undefined;
+    coverage?: number | undefined;
+    expiryDays?: number | undefined;
+}, {
+    maxItems?: number | undefined;
+    budget?: number | null | undefined;
+    coverage?: number | undefined;
+    expiryDays?: number | undefined;
+}>;
+export type TargetInput = z.infer<typeof targetSchema>;
+export interface TargetProfile {
+    maxItems: number;
+    budget: number | null;
+    coverage: number;
+    expiryDays: number;
+}
+export interface DataIssue {
+    code: string;
+    severity: "error" | "warning";
+    message: string;
+    itemId?: string;
+}
+export interface CollectionItem {
+    id: string;
+    name: string;
+    category: string;
+    tags: string[];
+    cost: number | null;
+    quantity: number | null;
+    acquired: string | null;
+    expires: string | null;
+    lastUsed: string | null;
+    condition: Condition;
+    notes: string | null;
+    dataFields: number;
+}
+export interface LoadedCollection {
+    items: CollectionItem[];
+    issues: DataIssue[];
+    source: string;
+    rawCount: number;
+}
+export interface Gap {
+    type: "category" | "expiry" | "dependency";
+    key: string;
+    missing: number;
+    severity: "high" | "medium" | "low";
+    message: string;
+}
+export interface Risk {
+    code: string;
+    severity: "critical" | "high" | "medium" | "low";
+    message: string;
+    impact: number;
+}
+export interface Constraint {
+    key: string;
+    label: string;
+    pass: boolean;
+    actual: unknown;
+    target: unknown;
+    message: string;
+}
+export interface DuplicateGroup {
+    key: string;
+    count: number;
+    ids: string[];
+    names: string[];
+}
+export interface Fix {
+    action: string;
+    impact: number;
+    effort: number;
+    score: number;
+    source: string;
+}
+export interface Analysis {
+    target: TargetProfile;
+    itemCount: number;
+    items: CollectionItem[];
+    categoryCounts: Record<string, number>;
+    unknownCategories: string[];
+    totalCost: number;
+    knownCostCount: number;
+    totalQuantity: number;
+    knownQuantityCount: number;
+    expired: CollectionItem[];
+    expiring: CollectionItem[];
+    metricRows: Array<{
+        id: string;
+        name: string;
+        value: number | null;
+    }>;
+    metricMean: number;
+    metricPassCount: number;
+    metricKnownCount: number;
+    categoryCoverage: Record<string, number>;
+    coverageScore: number;
+    conditionScore: number;
+    dataCompleteness: number;
+    readiness: number;
+    confidence: number;
+    gaps: Gap[];
+    risks: Risk[];
+    constraints: Constraint[];
+    duplicates: DuplicateGroup[];
+    variance: {
+        metric: {
+            count: number;
+            mean: number;
+            variance: number;
+            stddev: number;
+            min: number;
+            max: number;
+        };
+        categories: {
+            mean: number;
+            variance: number;
+        };
+        tagDiversity: number;
+    };
+    benchmark: {
+        rows: Array<{
+            metric: string;
+            value: number;
+            target: string;
+            pass: boolean;
+        }>;
+        passed: number;
+        total: number;
+        verdict: "strong" | "mixed" | "thin";
+    };
+    options: Array<{
+        name: string;
+        maxItems: number;
+        expected: Record<string, number>;
+        fit: number;
+    }>;
+    tradeoffs: Array<{
+        title: string;
+        current: string;
+        note: string;
+    }>;
+    checklist: Array<{
+        item: string;
+        done: boolean;
+    }>;
+    quickWins: Fix[];
+    fixes: Fix[];
+    nextSteps: Fix[];
+    questions: string[];
+    edgeCases: string[];
+    dataIssues: DataIssue[];
+    summary: {
+        items: number;
+        readiness: number;
+        confidence: number;
+        totalCost: number;
+        metricMean: number;
+        gaps: number;
+        risks: number;
+        duplicates: number;
+        dataIssues: number;
+    };
+}
+export declare function loadCollection(input: {
+    items?: unknown[];
+    content?: string;
+    path?: string;
+    cwd?: string;
+}): Promise<LoadedCollection>;
+export declare function normalizeTarget(input?: TargetInput): TargetProfile;
+export declare function analyze(loaded: LoadedCollection, targetInput?: TargetProfile): Analysis;
+export declare function changeSet(before: LoadedCollection, after: LoadedCollection): {
+    counts: {
+        before: number;
+        after: number;
+        added: number;
+        removed: number;
+        changed: number;
+    };
+    added: CollectionItem[];
+    removed: CollectionItem[];
+    changed: {
+        before: CollectionItem | undefined;
+        after: CollectionItem;
+    }[];
+};