dropmcp 0.1.0__tar.gz

dropmcp-0.1.0/.claude/skills/api-response-for-browser/SKILL.md

@@ -0,0 +1,100 @@
+---
+name: api-response-for-browser
+description: Enforces efficient API endpoint design when serving data to browsers. Minimise HTTP requests per page, use view models to shape data server-side, and choose between client-side and server-side filtering based on data volume. Use when writing or reviewing API endpoints, AJAX calls, frontend data fetching, view models, or any browser-to-server data requests.
+---
+
+# API Response Design for Browser Clients
+
+## Rule
+
+**Shape data on the server to match what the page needs. Minimise the number of HTTP requests per page.**
+
+Browsers enforce a parallel connection limit per domain (typically 6). Every additional request competes for those slots, increasing page load time and hurting user experience.
+
+## Core Principles
+
+1. **One request per page view** is the ideal. A small number (2–3) is acceptable when the data is logically independent and loaded in parallel. More than that needs justification.
+2. **Use view models** — build a server-side response object that mirrors the page structure. Do not make the browser assemble its own view from multiple generic entity endpoints.
+3. **Push logic to the server** — sorting, formatting, computed fields, conditional display flags. The browser should receive data that is ready to render.
+4. **Aggregate related data** — if a page shows a header, a list, and summary stats, return them in a single response, not three separate calls.
+
+## View Model Approach
+
+Build a dedicated response model per page or component that returns exactly what the UI needs:
+
+```csharp
+// GOOD — single endpoint returns everything the page needs
+public class OrderPageViewModel
+{
+    public OrderSummary Summary { get; set; }
+    public List<OrderLineItem> Lines { get; set; }
+    public CustomerInfo Customer { get; set; }
+    public List<string> AvailableActions { get; set; }
+}
+
+[HttpGet("orders/{id}/page")]
+public OrderPageViewModel GetOrderPage(int id) { ... }
+```
+
+```typescript
+// GOOD — one fetch, one response, everything the page needs
+const data = await fetch(`/api/orders/${id}/page`);
+```
+
+```csharp
+// BAD — browser makes three requests to assemble the same page
+[HttpGet("orders/{id}")]
+[HttpGet("orders/{id}/lines")]
+[HttpGet("customers/{customerId}")]
+```
+
+## Filtering Strategy
+
+Choose the filtering approach based on data volume and filter complexity:
+
+| Scenario | Approach |
+|----------|----------|
+| Small dataset, simple filters (< ~500 rows, 1–2 filter fields) | Return all data; filter client-side for instant UX |
+| Moderate dataset, simple filters | Return slightly more data than the default view to allow fast client-side filtering without round-trips |
+| Large dataset or complex filters (search, multi-field, range queries) | Filter server-side; browser sends filter params and receives filtered results |
+| Paginated data | Always server-side; return one page at a time |
+
+```typescript
+// GOOD — small dataset, simple filter: return all, filter in browser
+const [statusFilter, setStatusFilter] = useState("all");
+const filtered = items.filter(i => statusFilter === "all" || i.status === statusFilter);
+```
+
+```typescript
+// GOOD — large dataset, complex filter: call back to server
+const results = await fetch(`/api/products?category=${cat}&minPrice=${min}&maxPrice=${max}&q=${search}`);
+```
+
+```typescript
+// BAD — fetching thousands of rows to filter two fields in the browser
+const allProducts = await fetch("/api/products"); // returns 50,000 rows
+const filtered = allProducts.filter(p => p.price > min && p.price < max);
+```
+
+## Prohibited Patterns
+
+- **Chatty APIs** — multiple sequential requests to load a single page view
+- **Generic entity endpoints as the sole API surface for pages** — forcing the browser to join data from `/users`, `/orders`, `/products` separately
+- **Returning large datasets for client-side filtering** when the filter is complex or the data exceeds a few hundred rows
+- **Returning raw database models** — expose view models shaped for the UI, not ORM entities
+
+## Correct Patterns
+
+- One endpoint per page/view returning a composed view model
+- Server-side aggregation of related data into a single response
+- Pre-computed display values (formatted dates, status labels, computed totals)
+- Lightweight filter params sent to the server when data volume is large
+- Small over-fetch for simple client-side filters to avoid round-trips
+
+## When Designing a New Endpoint
+
+1. Identify the page or component that will consume the data
+2. List every piece of data the page displays
+3. Build a single view model that contains all of it
+4. Decide filtering strategy based on expected data volume
+5. Ensure the browser needs at most 1–3 requests to fully render the page

dropmcp-0.1.0/.claude/skills/no-browser-datetime/SKILL.md

@@ -0,0 +1,87 @@
+---
+name: no-browser-datetime
+description: Enforces that Date objects and datetime types are never used in browser/frontend code. Dates must be converted to strings on the server and passed as strings. Use when writing or reviewing frontend code that involves dates, timestamps, calendars, date pickers, or API responses containing dates.
+---
+
+# No DateTime in the Browser
+
+## Rule
+
+**Never use `Date` objects or datetime types in browser/frontend code.**
+
+All date/time conversion and formatting must happen on the server. The frontend receives and works with **strings only**.
+
+## Date String Format
+
+When dates need to be handled programmatically in the browser (e.g. calendar selection, date pickers, comparisons), use the string format:
+
+```
+YYYY-MM-DD
+```
+
+Examples: `"2026-03-22"`, `"2025-01-01"`
+
+For datetime values that include time, use:
+
+```
+YYYY-MM-DD HH:mm:ss
+```
+
+## What To Do
+
+| Scenario | Approach |
+|----------|----------|
+| Displaying a date | Server sends a pre-formatted display string (e.g. `"March 22, 2026"`) |
+| Date picker / calendar | Use `"YYYY-MM-DD"` strings; send the selected string back to the server |
+| Sorting by date | Sort `"YYYY-MM-DD"` strings lexicographically (this format sorts correctly as strings) |
+| Comparing dates | Compare `"YYYY-MM-DD"` strings directly |
+| Date arithmetic | Send the string to the server; let the server compute and return the result |
+| API request with date | Pass the `"YYYY-MM-DD"` string as-is |
+| API response with date | Server must return dates as pre-formatted strings, not ISO timestamps for the client to parse |
+
+## Prohibited Patterns
+
+```typescript
+// BAD — constructing Date objects in the browser
+const d = new Date();
+const d = new Date("2026-03-22");
+const d = new Date(timestamp);
+
+// BAD — using Date methods in the browser
+date.toLocaleDateString();
+date.getFullYear();
+Date.now();
+Date.parse(str);
+
+// BAD — date libraries in frontend bundles
+import dayjs from "dayjs";
+import { format } from "date-fns";
+import moment from "moment";
+```
+
+## Correct Patterns
+
+```typescript
+// GOOD — server sends display-ready strings
+interface Event {
+  title: string;
+  date: string;        // "YYYY-MM-DD"
+  displayDate: string;  // "March 22, 2026" — ready to render
+}
+
+// GOOD — date picker works with string values
+const [selectedDate, setSelectedDate] = useState<string>("2026-03-22");
+
+// GOOD — comparing date strings directly
+const isAfter = dateA > dateB; // works because YYYY-MM-DD sorts lexicographically
+
+// GOOD — sending date string to the server for computation
+const response = await fetch(`/api/next-business-day?from=${selectedDate}`);
+```
+
+## Server Responsibility
+
+The server must:
+1. Convert all dates to the agreed string formats before sending to the client
+2. Accept `"YYYY-MM-DD"` strings from the client
+3. Handle all timezone conversion, date arithmetic, and locale-specific formatting

dropmcp-0.1.0/.claude/skills/no-test-code-in-production/SKILL.md

@@ -0,0 +1,78 @@
+---
+name: no-test-code-in-production
+description: Enforces that mocks, stubs, fakes, and other test-only code are never placed in production source files. Use when writing, reviewing, or refactoring code that involves mocking, test doubles, dependency injection, or environment-specific configuration.
+---
+
+# No Test Code in Production
+
+## Core Rule
+
+Never place mocks, stubs, fakes, spy implementations, or any test-only code in production source files. Test doubles belong exclusively in test files and test directories.
+
+## What Counts as Test Code
+
+- Mock or fake implementations of interfaces/classes (e.g., `FakeUserRepository`, `MockHttpClient`)
+- Conditional logic that checks for a test environment to swap behavior (e.g., `if (env === 'test') { ... }`)
+- Test data factories or fixture builders
+- Imports of test frameworks or assertion libraries
+- In-memory substitutes created solely for testing (e.g., `InMemoryQueue`)
+
+## Allowed Exception: Environment-Specific Config Files
+
+Projects often have separate configuration files per environment. A dedicated test/dev config file is acceptable:
+
+```
+config/
+├── config.production.json
+├── config.staging.json
+├── config.development.json
+└── config.test.json        # ✅ This is fine
+```
+
+The key distinction: a **config file** that sets values for a test environment is not test code. A **source file** that contains mock implementations is.
+
+## Preferred Approach: Dependency Injection
+
+Instead of embedding mocks in production code, inject dependencies so tests can substitute their own implementations:
+
+### Do This
+
+Define abstractions in production code. Inject real implementations at runtime and test doubles in tests.
+
+```
+// Production: define the contract
+interface NotificationService { send(msg): Promise<void> }
+
+// Production: real implementation
+class EmailNotificationService implements NotificationService { ... }
+
+// Test file only: mock implementation
+class MockNotificationService implements NotificationService { ... }
+```
+
+### Don't Do This
+
+```
+// ❌ Production file with a test-only class
+class MockNotificationService implements NotificationService {
+  async send(msg) { /* no-op for tests */ }
+}
+
+// ❌ Runtime check to swap in test behavior
+function getNotificationService() {
+  if (process.env.NODE_ENV === 'test') {
+    return new MockNotificationService();
+  }
+  return new EmailNotificationService();
+}
+```
+
+## Review Checklist
+
+When writing or reviewing code, verify:
+
+- [ ] No mock/fake/stub classes exist in production source directories
+- [ ] No `if test/dev` branching to swap in test doubles at runtime
+- [ ] Dependencies are injected, not hard-coded with test fallbacks
+- [ ] Test-only imports (e.g., `jest`, `unittest.mock`, `Moq`) do not appear in production files
+- [ ] Environment-specific configs are in dedicated config files, not inline conditionals

dropmcp-0.1.0/.claude/skills/preserve-existing-tests/SKILL.md

@@ -0,0 +1,67 @@
+---
+name: preserve-existing-tests
+description: Prevents modification of existing tests and test data unless behavior has explicitly changed. Existing passing tests are proof that current behavior is correct — changing them risks hiding bugs. Use when editing, refactoring, or fixing code that has associated tests, or when reviewing changes that modify test files.
+---
+
+# Preserve Existing Tests
+
+## Core Rule
+
+**Never modify existing tests or test data.** If existing tests fail after your changes, that is a signal you may have introduced a bug — not that the tests are wrong.
+
+Only modify an existing test when the user has explicitly stated that the behavior under test should change.
+
+## Why This Matters
+
+Existing passing tests are the specification for current correct behavior. Changing a test to make it pass after a code change silently redefines "correct" and can mask regressions.
+
+## Decision Flow
+
+```
+Existing test fails after your code change
+│
+├── Was the behavior change explicitly requested?
+│   ├── YES → Update the test to match the new expected behavior
+│   └── NO  → Your code change likely has a bug — fix the code, not the test
+│
+└── Need to cover new behavior?
+    └── Add a new test case — don't modify existing ones
+```
+
+## What NOT To Do
+
+- **Don't update assertions** to match new output without confirming the output change is intentional
+- **Don't delete tests** that fail after a refactor
+- **Don't modify test fixtures or test data** to accommodate implementation changes
+- **Don't weaken test conditions** (e.g., changing exact match to contains, loosening thresholds)
+- **Don't rename or restructure tests** as part of an unrelated change
+
+## What To Do
+
+- **Add new test cases** for new behavior alongside existing tests
+- **Fix production code** when existing tests break unexpectedly
+- **Ask the user** if you're unsure whether a behavior change is intentional
+- **Keep existing assertions intact** even when adding new ones
+
+## Examples
+
+### Refactoring — Tests Must Still Pass As-Is
+
+If you refactor a function's internals without changing its contract, all existing tests must pass without modification. A failing test means the refactor changed observable behavior.
+
+### Adding a Feature — Add New Tests
+
+When adding a new feature to an existing module, write new test cases for the new behavior. Do not alter existing test cases for the module.
+
+### Bug Fix — Verify Against Existing Tests
+
+When fixing a bug, existing tests should continue to pass. Add a new test that reproduces the bug and verifies the fix.
+
+## Review Checklist
+
+When reviewing changes that include test file modifications:
+
+- [ ] Is each test modification justified by an explicitly requested behavior change?
+- [ ] Are existing assertions preserved, not weakened or removed?
+- [ ] Are new behaviors covered by new test cases rather than modified existing ones?
+- [ ] Is test data/fixture modification necessary, or is the production code the real problem?

dropmcp-0.1.0/.claude/skills/react-component-layout/SKILL.md

@@ -0,0 +1,130 @@
+---
+name: react-component-layout
+description: Enforces that React component code mirrors the visual layout of the UI. Code structure should reflect UI structure so a developer can see the same borders and divisions in the code as on screen. Use when writing, reviewing, or refactoring React components, page layouts, or UI composition.
+---
+
+# React Component Layout
+
+Structure React code so that reading it feels like looking at the UI. A developer should be able to glance at the JSX and immediately see the same major sections, divisions, and hierarchy that appear on screen.
+
+## Core Principles
+
+### 1. Code Mirrors the UI
+
+Organize JSX so its nesting and grouping match the visual layout. If the UI has a header, a sidebar, and a main content area, those should be obvious top-level blocks in the JSX — not buried inside conditionals or abstracted away at the page level.
+
+```tsx
+function DashboardPage() {
+  return (
+    <PageShell>
+      <DashboardHeader />
+
+      <div className="dashboard-body">
+        <DashboardSidebar />
+        <DashboardContent reports={reports} />
+      </div>
+
+      <DashboardFooter />
+    </PageShell>
+  );
+}
+```
+
+Reading this component instantly reveals: header on top, sidebar + content in the middle, footer at the bottom — exactly what the user sees.
+
+### 2. One Top-Level Page Component Per Route
+
+Each page gets a single component that acts as its layout blueprint. This component does **only** composition — it arranges sections, it does not contain business logic or deep markup.
+
+```tsx
+function SettingsPage() {
+  return (
+    <PageShell title="Settings">
+      <SettingsTabs activeTab={activeTab} onTabChange={setActiveTab} />
+      <SettingsPanel tab={activeTab} />
+    </PageShell>
+  );
+}
+```
+
+The page component answers: "What are the major pieces of this screen and how are they arranged?"
+
+### 3. Keep Components Focused
+
+Each component should own one visually distinct region of the UI. When a component starts doing too much — handling multiple unrelated sections, mixing layout with fine-grained markup — split it.
+
+Signs a component needs splitting:
+- It renders multiple visually distinct areas that could be understood independently
+- You have to scroll through unrelated markup to find what you're looking for
+- The JSX nesting no longer maps to what you see on screen
+
+### 4. Hide Complexity in Well-Named Extractions
+
+When logic or markup grows complex, extract it into a method or component whose **name describes the UI it produces**. The name replaces the need for a comment.
+
+**Extract render helpers for conditional or computed UI chunks:**
+
+```tsx
+function OrderSummary({ order }: Props) {
+  return (
+    <Card>
+      <OrderLineItems items={order.items} />
+      <PricingBreakdown subtotal={order.subtotal} tax={order.tax} />
+      {order.discount && <AppliedDiscount discount={order.discount} />}
+      <OrderTotal total={order.total} />
+    </Card>
+  );
+}
+```
+
+Not:
+
+```tsx
+function OrderSummary({ order }: Props) {
+  return (
+    <Card>
+      {/* line items section */}
+      <div className="line-items">
+        {order.items.map(item => (
+          <div key={item.id} className="line-item">
+            <span>{item.name}</span>
+            <span>{item.qty} × {item.price}</span>
+          </div>
+        ))}
+      </div>
+      {/* pricing */}
+      <div className="pricing">
+        <div>Subtotal: {order.subtotal}</div>
+        <div>Tax: {order.tax}</div>
+      </div>
+      {/* ... more inline markup ... */}
+    </Card>
+  );
+}
+```
+
+The first version reads like a description of the UI. The second requires comments to navigate.
+
+### 5. Names Are the Documentation
+
+Component and function names should describe **what the user sees**, not implementation details. If the name is clear, no comment is needed.
+
+| Bad | Good |
+|-----|------|
+| `renderSection2` | `BillingAddressForm` |
+| `handleClick` | `submitPayment` |
+| `DataDisplay` | `RevenueChart` |
+| `getItems` | `buildNavigationLinks` |
+| `InfoBox` | `ShippingEstimate` |
+
+Ask: "If I read just the names in the JSX, do I know what the screen looks like?" If not, rename.
+
+## Applying These Principles
+
+When writing or reviewing React components:
+
+1. **Start from the page level.** Write the top-level page component first as a layout skeleton of named sections.
+2. **Check the mirror.** Read the JSX — does the nesting match the visual hierarchy? Would someone unfamiliar with the code recognize the UI from reading it?
+3. **Extract, don't inline.** When markup grows beyond a focused visual region, extract a component or helper named after what it renders.
+4. **Name before you comment.** If you're tempted to add a comment explaining a section of JSX, extract it into a well-named component instead.
+5. **Keep page components thin.** They compose sections — they don't contain implementation detail like API calls, complex state, or deep markup trees.

dropmcp-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,146 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+    tags: ["v*"]
+  pull_request:
+
+jobs:
+  test-python:
+    runs-on: ubuntu-24.04
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: "22"
+          cache: npm
+          cache-dependency-path: client/package-lock.json
+
+      - name: Build catalog UI
+        run: |
+          cd client
+          npm ci
+          npm run build
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install package
+        run: pip install -e ".[dev,otel]"
+
+      - name: Verify SPA is packaged
+        run: |
+          python -c "
+          from importlib import resources
+          from pathlib import Path
+          dist = Path(resources.files('dropmcp') / 'static' / 'dist')
+          assert (dist / 'index.html').is_file(), 'SPA index.html missing from wheel'
+          "
+
+      - name: Ruff
+        run: ruff check src
+
+      - name: pytest
+        run: pytest
+
+  test-ui:
+    runs-on: ubuntu-24.04
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: "22"
+          cache: npm
+          cache-dependency-path: client/package-lock.json
+
+      - name: Install and test UI
+        run: |
+          cd client
+          npm ci
+          npx playwright install --with-deps chromium
+          npm run build
+          npm test
+
+      - name: Upload Playwright report
+        if: failure()
+        uses: actions/upload-artifact@v4
+        with:
+          name: playwright-report
+          path: client/playwright-report/
+
+  build-wheel:
+    runs-on: ubuntu-24.04
+    needs: [test-python, test-ui]
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: "22"
+          cache: npm
+          cache-dependency-path: client/package-lock.json
+
+      - name: Build catalog UI
+        run: |
+          cd client
+          npm ci
+          npm run build
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Build wheel
+        run: pip install build && python -m build
+
+      - name: Upload wheel artifact
+        uses: actions/upload-artifact@v4
+        with:
+          name: dropmcp-wheel
+          path: dist/*.whl
+
+  publish-pypi:
+    runs-on: ubuntu-24.04
+    needs: [build-wheel]
+    if: startsWith(github.ref, 'refs/tags/v')
+    environment: pypi
+    permissions:
+      id-token: write  # required for trusted publishing
+      contents: write  # required to create GitHub releases
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: "22"
+          cache: npm
+          cache-dependency-path: client/package-lock.json
+
+      - name: Build catalog UI
+        run: |
+          cd client
+          npm ci
+          npm run build
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Build distributions
+        run: pip install build && python -m build
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+
+      - name: Create GitHub Release
+        env:
+          GH_TOKEN: ${{ github.token }}
+        run: |
+          gh release create "${{ github.ref_name }}" \
+            dist/*.whl dist/*.tar.gz \
+            --title "${{ github.ref_name }}" \
+            --generate-notes