@caoscompanybr/merlin 3.5.0

package/.merlin-core/skills/general/mcp-builder/SKILL.md

@@ -0,0 +1,92 @@
+---
+name: mcp-builder
+description: Guide for creating high-quality MCP (Model Context Protocol) servers that enable LLMs to interact with external services through well-designed tools. Use when building MCP servers to integrate external APIs or services, whether in Python (FastMCP) or Node/TypeScript (MCP SDK).
+license: MIT (Anthropic)
+compatibility: claude-code
+metadata:
+  source: anthropic/skills
+  imported: 2026-03-15
+  version: "1.0"
+  auto_activate: [mcp-build, mcp-server, mcp-create, model-context-protocol]
+---
+
+# MCP Server Development Guide
+
+## Overview
+
+Create MCP (Model Context Protocol) servers that enable LLMs to interact with external services through well-designed tools. The quality of an MCP server is measured by how well it enables LLMs to accomplish real-world tasks.
+
+## High-Level Workflow
+
+Creating a high-quality MCP server involves four main phases:
+
+### Phase 1: Deep Research and Planning
+
+1. **Understand Modern MCP Design**
+   - Balance API coverage with workflow tools
+   - Use clear, descriptive tool names with consistent prefixes
+   - Design tools that return focused, relevant data
+   - Error messages should guide agents toward solutions
+
+2. **Study MCP Protocol Documentation**
+   - Start with sitemap: `https://modelcontextprotocol.io/sitemap.xml`
+   - Fetch pages with `.md` suffix for markdown format
+   - Key areas: specification, transports (streamable HTTP, stdio), tool/resource/prompt definitions
+
+3. **Study Framework Documentation**
+   - **Recommended stack**: TypeScript (high-quality SDK, good AI code generation)
+   - **Transport**: Streamable HTTP for remote, stdio for local
+   - TypeScript SDK: `https://raw.githubusercontent.com/modelcontextprotocol/typescript-sdk/main/README.md`
+   - Python SDK: `https://raw.githubusercontent.com/modelcontextprotocol/python-sdk/main/README.md`
+
+4. **Plan Implementation**
+   - Review service API docs, auth requirements, data models
+   - List endpoints to implement, starting with most common operations
+
+### Phase 2: Implementation
+
+1. **Set Up Project Structure** — Use language-appropriate patterns
+2. **Implement Core Infrastructure** — API client, error handling, pagination, response formatting
+3. **Implement Tools** — For each tool:
+   - Input Schema (Zod/Pydantic)
+   - Output Schema (structuredContent where possible)
+   - Clear tool description
+   - Async/await for I/O
+   - Proper error handling with actionable messages
+   - Annotations: readOnlyHint, destructiveHint, idempotentHint, openWorldHint
+
+### Phase 3: Review and Test
+
+- No duplicated code (DRY)
+- Consistent error handling
+- Full type coverage
+- Clear tool descriptions
+- Build verification (`npm run build` / `python -m py_compile`)
+- Test with MCP Inspector: `npx @modelcontextprotocol/inspector`
+
+### Phase 4: Create Evaluations
+
+Create 10 evaluation questions testing LLM effectiveness with your MCP server:
+
+- Independent, read-only, complex, realistic, verifiable, stable
+- Output as XML with `<evaluation><qa_pair>` structure
+
+## Merlin Integration
+
+Merlin treats MCP servers as first-class capabilities (Constitution Article VI — MCP First).
+
+Configure in `.mcp.json` at project root:
+
+```json
+{
+  "mcpServers": {
+    "my-server": {
+      "command": "node",
+      "args": ["path/to/server.js"],
+      "env": {}
+    }
+  }
+}
+```
+
+The framework's capability mapper automatically discovers MCP tools and makes them available to agents.

package/.merlin-core/skills/general/network-debug/SKILL.md

@@ -0,0 +1,51 @@
+---
+name: network-debug
+description: Inspects network requests, API calls, and HTTP errors using browser MCP capabilities. Helps debug CORS, 404s, 500s, and failing fetches.
+license: Apache-2.0
+metadata:
+  author: merlin-framework
+  version: "3.0.0"
+  auto_activate:
+    [network-debug, cors-error, http-error, api-timeout, fetch-fail]
+  tool_reminders:
+    [
+      Use browser:network MCP to inspect actual API calls — don't guess from code alone,
+      Check CORS headers,
+      status codes,
+      and response bodies for debugging,
+    ]
+---
+
+## Network Debug Protocol
+
+When debugging network issues (CORS, failing API calls, HTTP errors):
+
+### 1. Identify the Request
+
+- Find the fetch/XHR call in the codebase
+- Identify the URL, method, headers, and body
+
+### 2. Inspect Live Traffic (if browser MCP available)
+
+- Use `browser:network` to capture actual requests/responses
+- Filter by URL pattern, method, or status code
+- Compare actual headers against expected headers
+
+### 3. Common Patterns
+
+| Symptom        | Likely Cause    | Check                                         |
+| -------------- | --------------- | --------------------------------------------- |
+| CORS error     | Missing headers | Response `Access-Control-Allow-Origin` header |
+| 404            | Wrong URL/route | API route definition vs fetch URL             |
+| 500            | Server crash    | Server logs + stack trace                     |
+| Empty response | Serialization   | Content-Type header + response body           |
+| Timeout        | Slow handler    | Response time in network tab                  |
+
+### 4. Graceful Degradation
+
+If browser MCP is not available, fall back to:
+
+- Reading server logs via Bash
+- Grepping for route definitions
+- Checking middleware chain for CORS/auth issues
+- Using `curl` commands to test endpoints manually

package/.merlin-core/skills/general/next-best-practices/SKILL.md

@@ -0,0 +1,177 @@
+---
+name: next-best-practices
+description: "Next.js best practices from the official Vercel team — App Router file conventions, RSC boundaries, async patterns (Next.js 15+), data fetching strategies, error handling, route handlers, image/font/script optimization, metadata & OG generation, bundling, hydration debugging, self-hosting, and parallel routes. Use when building, reviewing, or debugging any Next.js application."
+license: MIT
+metadata:
+  source: vercel-labs/next-skills
+  imported: 2026-03-15
+  version: "1.0.0"
+  auto_activate: [nextjs, next-app, app-router, server-component, next-api]
+  file_triggers: [**/next.config.*, **/app/**/page.tsx, **/app/**/layout.tsx]
+---
+
+# Next.js Best Practices
+
+Apply these rules when writing or reviewing Next.js code.
+
+## File Conventions
+
+See `references/file-conventions.md` for:
+
+- Project structure and special files
+- Route segments (dynamic, catch-all, groups)
+- Parallel and intercepting routes
+- Middleware rename in v16 (middleware → proxy)
+
+## RSC Boundaries
+
+Detect invalid React Server Component patterns.
+
+See `references/rsc-boundaries.md` for:
+
+- Async client component detection (invalid)
+- Non-serializable props detection
+- Server Action exceptions
+
+## Async Patterns
+
+Next.js 15+ async API changes.
+
+See `references/async-patterns.md` for:
+
+- Async `params` and `searchParams`
+- Async `cookies()` and `headers()`
+- Migration codemod
+
+## Runtime Selection
+
+See `references/runtime-selection.md` for:
+
+- Default to Node.js runtime
+- When Edge runtime is appropriate
+
+## Directives
+
+See `references/directives.md` for:
+
+- `'use client'`, `'use server'` (React)
+- `'use cache'` (Next.js)
+
+## Functions
+
+See `references/functions.md` for:
+
+- Navigation hooks: `useRouter`, `usePathname`, `useSearchParams`, `useParams`
+- Server functions: `cookies`, `headers`, `draftMode`, `after`
+- Generate functions: `generateStaticParams`, `generateMetadata`
+
+## Error Handling
+
+See `references/error-handling.md` for:
+
+- `error.tsx`, `global-error.tsx`, `not-found.tsx`
+- `redirect`, `permanentRedirect`, `notFound`
+- `forbidden`, `unauthorized` (auth errors)
+- `unstable_rethrow` for catch blocks
+
+## Data Patterns
+
+See `references/data-patterns.md` for:
+
+- Server Components vs Server Actions vs Route Handlers
+- Avoiding data waterfalls (`Promise.all`, Suspense, preload)
+- Client component data fetching
+
+## Route Handlers
+
+See `references/route-handlers.md` for:
+
+- `route.ts` basics
+- GET handler conflicts with `page.tsx`
+- Environment behavior (no React DOM)
+- When to use vs Server Actions
+
+## Metadata & OG Images
+
+See `references/metadata.md` for:
+
+- Static and dynamic metadata
+- `generateMetadata` function
+- OG image generation with `next/og`
+- File-based metadata conventions
+
+## Image Optimization
+
+See `references/image.md` for:
+
+- Always use `next/image` over `<img>`
+- Remote images configuration
+- Responsive `sizes` attribute
+- Blur placeholders
+- Priority loading for LCP
+
+## Font Optimization
+
+See `references/font.md` for:
+
+- `next/font` setup
+- Google Fonts, local fonts
+- Tailwind CSS integration
+- Preloading subsets
+
+## Bundling
+
+See `references/bundling.md` for:
+
+- Server-incompatible packages
+- CSS imports (not link tags)
+- Polyfills (already included)
+- ESM/CommonJS issues
+- Bundle analysis
+
+## Scripts
+
+See `references/scripts.md` for:
+
+- `next/script` vs native script tags
+- Inline scripts need `id`
+- Loading strategies
+- Google Analytics with `@next/third-parties`
+
+## Hydration Errors
+
+See `references/hydration-error.md` for:
+
+- Common causes (browser APIs, dates, invalid HTML)
+- Debugging with error overlay
+- Fixes for each cause
+
+## Suspense Boundaries
+
+See `references/suspense-boundaries.md` for:
+
+- CSR bailout with `useSearchParams` and `usePathname`
+- Which hooks require Suspense boundaries
+
+## Parallel & Intercepting Routes
+
+See `references/parallel-routes.md` for:
+
+- Modal patterns with `@slot` and `(.)` interceptors
+- `default.tsx` for fallbacks
+- Closing modals correctly with `router.back()`
+
+## Self-Hosting
+
+See `references/self-hosting.md` for:
+
+- `output: 'standalone'` for Docker
+- Cache handlers for multi-instance ISR
+- What works vs needs extra setup
+
+## Debug Tricks
+
+See `references/debug-tricks.md` for:
+
+- MCP endpoint for AI-assisted debugging
+- Rebuild specific routes with `--debug-build-paths`

package/.merlin-core/skills/general/next-best-practices/references/async-patterns.md

@@ -0,0 +1,87 @@
+# Async Patterns
+
+In Next.js 15+, `params`, `searchParams`, `cookies()`, and `headers()` are asynchronous.
+
+## Async Params and SearchParams
+
+Always type them as `Promise<...>` and await them.
+
+### Pages and Layouts
+
+```tsx
+type Props = { params: Promise<{ slug: string }> };
+
+export default async function Page({ params }: Props) {
+  const { slug } = await params;
+}
+```
+
+### Route Handlers
+
+```tsx
+export async function GET(
+  request: Request,
+  { params }: { params: Promise<{ id: string }> },
+) {
+  const { id } = await params;
+}
+```
+
+### SearchParams
+
+```tsx
+type Props = {
+  params: Promise<{ slug: string }>;
+  searchParams: Promise<{ query?: string }>;
+};
+
+export default async function Page({ params, searchParams }: Props) {
+  const { slug } = await params;
+  const { query } = await searchParams;
+}
+```
+
+### Synchronous Components
+
+Use `React.use()` for non-async components:
+
+```tsx
+import { use } from "react";
+
+type Props = { params: Promise<{ slug: string }> };
+
+export default function Page({ params }: Props) {
+  const { slug } = use(params);
+}
+```
+
+### generateMetadata
+
+```tsx
+type Props = { params: Promise<{ slug: string }> };
+
+export async function generateMetadata({ params }: Props): Promise<Metadata> {
+  const { slug } = await params;
+  return { title: slug };
+}
+```
+
+## Async Cookies and Headers
+
+```tsx
+import { cookies, headers } from "next/headers";
+
+export default async function Page() {
+  const cookieStore = await cookies();
+  const headersList = await headers();
+
+  const theme = cookieStore.get("theme");
+  const userAgent = headersList.get("user-agent");
+}
+```
+
+## Migration Codemod
+
+```bash
+npx @next/codemod@latest next-async-request-api .
+```

package/.merlin-core/skills/general/next-best-practices/references/bundling.md

@@ -0,0 +1,182 @@
+# Bundling
+
+Fix common bundling issues with third-party packages.
+
+## Server-Incompatible Packages
+
+Some packages use browser APIs (`window`, `document`, `localStorage`) and fail in Server Components.
+
+### Error Signs
+
+```
+ReferenceError: window is not defined
+ReferenceError: document is not defined
+ReferenceError: localStorage is not defined
+Module not found: Can't resolve 'fs'
+```
+
+### Solution 1: Mark as Client-Only
+
+If the package is only needed on client:
+
+```tsx
+// Bad: Fails - package uses window
+import SomeChart from "some-chart-library";
+
+export default function Page() {
+  return <SomeChart />;
+}
+
+// Good: Use dynamic import with ssr: false
+import dynamic from "next/dynamic";
+
+const SomeChart = dynamic(() => import("some-chart-library"), {
+  ssr: false,
+});
+
+export default function Page() {
+  return <SomeChart />;
+}
+```
+
+### Solution 2: Externalize from Server Bundle
+
+For packages that should run on server but have bundling issues:
+
+```js
+// next.config.js
+module.exports = {
+  serverExternalPackages: ["problematic-package"],
+};
+```
+
+Use this for:
+
+- Packages with native bindings (sharp, bcrypt)
+- Packages that don't bundle well (some ORMs)
+- Packages with circular dependencies
+
+### Solution 3: Client Component Wrapper
+
+Wrap the entire usage in a client component:
+
+```tsx
+// components/ChartWrapper.tsx
+"use client";
+
+import { Chart } from "chart-library";
+
+export function ChartWrapper(props) {
+  return <Chart {...props} />;
+}
+
+// app/page.tsx (server component)
+import { ChartWrapper } from "@/components/ChartWrapper";
+
+export default function Page() {
+  return <ChartWrapper data={data} />;
+}
+```
+
+## CSS Imports
+
+Import CSS files instead of using `<link>` tags. Next.js handles bundling and optimization.
+
+```tsx
+// Bad: Manual link tag
+<link rel="stylesheet" href="/styles.css" />;
+
+// Good: Import CSS
+import "./styles.css";
+
+// Good: CSS Modules
+import styles from "./Button.module.css";
+```
+
+## Polyfills
+
+Next.js includes common polyfills automatically. Don't load redundant ones from polyfill.io or similar CDNs.
+
+Already included: `Array.from`, `Object.assign`, `Promise`, `fetch`, `Map`, `Set`, `Symbol`, `URLSearchParams`, and 50+ others.
+
+```tsx
+// Bad: Redundant polyfills
+<script src="https://polyfill.io/v3/polyfill.min.js?features=fetch,Promise,Array.from" />
+
+// Good: Next.js includes these automatically
+```
+
+## ESM/CommonJS Issues
+
+### Error Signs
+
+```
+SyntaxError: Cannot use import statement outside a module
+Error: require() of ES Module
+Module not found: ESM packages need to be imported
+```
+
+### Solution: Transpile Package
+
+```js
+// next.config.js
+module.exports = {
+  transpilePackages: ["some-esm-package", "another-package"],
+};
+```
+
+## Common Problematic Packages
+
+| Package         | Issue           | Solution                                                        |
+| --------------- | --------------- | --------------------------------------------------------------- |
+| `sharp`         | Native bindings | `serverExternalPackages: ['sharp']`                             |
+| `bcrypt`        | Native bindings | `serverExternalPackages: ['bcrypt']` or use `bcryptjs`          |
+| `canvas`        | Native bindings | `serverExternalPackages: ['canvas']`                            |
+| `recharts`      | Uses window     | `dynamic(() => import('recharts'), { ssr: false })`             |
+| `react-quill`   | Uses document   | `dynamic(() => import('react-quill'), { ssr: false })`          |
+| `mapbox-gl`     | Uses window     | `dynamic(() => import('mapbox-gl'), { ssr: false })`            |
+| `monaco-editor` | Uses window     | `dynamic(() => import('@monaco-editor/react'), { ssr: false })` |
+| `lottie-web`    | Uses document   | `dynamic(() => import('lottie-react'), { ssr: false })`         |
+
+## Bundle Analysis
+
+Analyze bundle size with the built-in analyzer (Next.js 16.1+):
+
+```bash
+next experimental-analyze
+```
+
+This opens an interactive UI to:
+
+- Filter by route, environment (client/server), and type
+- Inspect module sizes and import chains
+- View treemap visualization
+
+Save output for comparison:
+
+```bash
+next experimental-analyze --output
+# Output saved to .next/diagnostics/analyze
+```
+
+Reference: https://nextjs.org/docs/app/guides/package-bundling
+
+## Migrating from Webpack to Turbopack
+
+Turbopack is the default bundler in Next.js 15+. If you have custom webpack config, migrate to Turbopack-compatible alternatives:
+
+```js
+// next.config.js
+module.exports = {
+  // Good: Works with Turbopack
+  serverExternalPackages: ["package"],
+  transpilePackages: ["package"],
+
+  // Bad: Webpack-only - migrate away from this
+  webpack: (config) => {
+    // custom webpack config
+  },
+};
+```
+
+Reference: https://nextjs.org/docs/app/building-your-application/upgrading/from-webpack-to-turbopack