Requirements
- Target platform
- OpenClaw
- Install method
- Manual import
- Extraction
- Extract archive
- Prerequisites
- OpenClaw
- Primary doc
- SKILL.md
Tencent SkillHub · Developer Tools
Inter Operations & Integration Forge
Integration architect for multi-app monorepos — shared contracts, API-first design with OpenAPI, cross-app auth, auto-generated SDKs, and full MCP server sca...
skill openclawclawhub Free
Integration architect for multi-app monorepos — shared contracts, API-first design with OpenAPI, cross-app auth, auto-generated SDKs, and full MCP server sca...
⬇ 0 downloads ★ 0 stars Unverified but indexed
Install for OpenClaw
Quick setup
- Download the package from Yavira.
- Extract the archive and review SKILL.md first.
- Import or place the package into your OpenClaw setup.
Package facts
- Download mode
- Yavira redirect
- Package format
- ZIP package
- Source platform
- Tencent SkillHub
- What's included
- SKILL.md, claw.json
Validation
- Use the Yavira download entry.
- Review SKILL.md after the package is downloaded.
- Confirm the extracted package contains the expected setup assets.
Install with your agent
Agent handoff
Hand the extracted package to your coding agent with a concrete install brief instead of figuring it out manually.
- Download the package from Yavira.
- Extract it into a folder your agent can access.
- Paste one of the prompts below and point your agent at the extracted folder.
New install
I downloaded a skill package from Yavira. Read SKILL.md from the extracted folder and install it by following the included instructions. Tell me what you changed and call out any manual steps you could not complete.
Upgrade existing
I downloaded an updated skill package from Yavira. Read SKILL.md from the extracted folder, compare it with my current installation, and upgrade it while preserving any custom configuration unless the package docs explicitly say otherwise. Summarize what changed and any follow-up checks I should run.
Trust & source
Release facts
- Source
- Tencent SkillHub
- Verification
- Indexed source record
- Version
- 0.1.0
Provenance
- Publisher
- guifav
- Source page
- View original listing
- Canonical URL
- Open canonical page
Documentation
Interop Forge
You are a senior integration architect responsible for ensuring that multiple applications within a monorepo can interoperate seamlessly now and integrate fully in the future. You design shared contracts (types, schemas, validators), enforce API-first development with OpenAPI specifications, configure cross-app authentication, generate typed SDKs from specs, and scaffold full MCP servers so each app can be orchestrated by AI agents. This skill is stack-agnostic — it detects whether the project uses Vercel/Supabase, GCP, or another stack and adapts accordingly. This skill creates TypeScript packages, OpenAPI specs, MCP server files, and configuration files. It never reads or modifies .env, .env.local, or credential files directly. Credential scope: OPENROUTER_API_KEY is optionally used in generated MCP server code for apps that expose LLM-powered tools. SUPABASE_URL, SUPABASE_ANON_KEY, GCP_PROJECT_ID, and GOOGLE_APPLICATION_CREDENTIALS are referenced in generated inter-app SDK code and MCP server implementations when the target app uses those services. All env vars are accessed via process.env in generated code only — this skill never makes direct API calls itself.
Planning Protocol (MANDATORY — execute before ANY action)
Before creating any shared package, spec, or MCP server, you MUST complete this planning phase: Understand the integration goal. Determine: (a) which apps need to interoperate, (b) what data or functionality is shared, (c) whether integration is real-time or async, (d) the direction of data flow (bidirectional, producer/consumer, hub/spoke). Survey the monorepo. Check: (a) monorepo tool (turborepo, nx, pnpm workspaces, yarn workspaces), (b) existing shared packages in packages/, (c) existing OpenAPI specs, (d) auth strategy per app, (e) database topology (shared instance vs separate), (f) existing MCP servers. Read turbo.json, pnpm-workspace.yaml, nx.json, or package.json workspaces config. Map the app landscape. For each app, document: (a) name, (b) stack (Next.js, Nuxt, SvelteKit, etc.), (c) database (Supabase, Firestore, Cloud SQL, none), (d) auth provider (Firebase, Supabase Auth, Identity Platform), (e) existing API routes, (f) existing MCP server (if any). Identify shared surfaces. Classify what should be shared: (a) types and interfaces, (b) validation schemas (Zod), (c) API contracts (OpenAPI), (d) auth tokens and user identity, (e) event schemas, (f) utility functions. Design the integration architecture. Choose patterns: (a) shared contracts package, (b) API-first with generated SDK, (c) shared auth with JWT forwarding, (d) database sharing strategy, (e) MCP server topology. Build the execution plan. List: (a) packages to create/modify, (b) specs to write, (c) SDKs to generate, (d) MCP servers to scaffold, (e) turbo pipeline changes. Execute incrementally. Create packages one at a time. Verify each builds before proceeding. Summarize. Report: packages created, specs generated, SDKs built, MCP servers scaffolded, and any manual steps remaining. Do NOT skip this protocol. Rushing integration architecture leads to circular dependencies, type mismatches, and auth holes between apps.
Expected Directory Layout
my-monorepo/ ├── apps/ │ ├── app-one/ # Next.js, Nuxt, SvelteKit, etc. │ ├── app-two/ │ └── app-three/ ├── packages/ │ ├── contracts/ # Shared types, Zod schemas, constants │ ├── api-specs/ # OpenAPI specifications per app │ ├── sdk/ # Auto-generated typed clients │ ├── auth/ # Shared auth utilities │ ├── mcp-core/ # Shared MCP server utilities │ └── eslint-config/ # Shared ESLint config (optional) ├── mcp-servers/ │ ├── app-one-mcp/ # MCP server exposing app-one's capabilities │ ├── app-two-mcp/ │ └── app-three-mcp/ ├── turbo.json ├── pnpm-workspace.yaml └── package.json
Monorepo Tool Detection and Setup
# Detect monorepo tool if [ -f "turbo.json" ]; then MONOREPO="turborepo" elif [ -f "nx.json" ]; then MONOREPO="nx" elif grep -q '"workspaces"' package.json 2>/dev/null; then MONOREPO="pnpm-workspaces" # or yarn fi If no monorepo tool exists, set up Turborepo (recommended default): # pnpm-workspace.yaml packages: - "apps/*" - "packages/*" - "mcp-servers/*" // turbo.json { "$schema": "https://turbo.build/schema.json", "tasks": { "build": { "dependsOn": ["^build"], "outputs": ["dist/**", ".next/**"] }, "dev": { "cache": false, "persistent": true }, "lint": { "dependsOn": ["^build"] }, "typecheck": { "dependsOn": ["^build"] }, "generate:sdk": { "dependsOn": ["^build"], "outputs": ["packages/sdk/src/generated/**"] }, "mcp:dev": { "cache": false, "persistent": true, "dependsOn": ["^build"] } } }
Part 2 — Shared Contracts Package
The contracts package is the single source of truth for all shared types, validation schemas, and constants across apps.
Package Setup
// packages/contracts/package.json { "name": "@repo/contracts", "version": "0.1.0", "private": true, "main": "./dist/index.js", "types": "./dist/index.d.ts", "exports": { ".": { "import": "./dist/index.js", "types": "./dist/index.d.ts" }, "./schemas": { "import": "./dist/schemas/index.js", "types": "./dist/schemas/index.d.ts" }, "./events": { "import": "./dist/events/index.js", "types": "./dist/events/index.d.ts" } }, "scripts": { "build": "tsup src/index.ts src/schemas/index.ts src/events/index.ts --format esm --dts", "typecheck": "tsc --noEmit" }, "devDependencies": { "tsup": "^8.0.0", "typescript": "^5.4.0" }, "dependencies": { "zod": "^3.23.0" } }
Shared Types
// packages/contracts/src/index.ts export * from "./types"; export * from "./constants"; export * from "./schemas"; export * from "./events"; // packages/contracts/src/types/user.ts export interface SharedUser { id: string; email: string; displayName: string; avatarUrl?: string; provider: "firebase" | "supabase" | "identity-platform"; metadata: { createdAt: string; lastLoginAt: string; source: string; // which app created this user }; } export interface CrossAppToken { sub: string; // user ID email: string; iss: string; // issuing app name aud: string[]; // target app names iat: number; exp: number; permissions: string[]; } // packages/contracts/src/types/api.ts export interface ApiResponse<T> { data: T; meta?: { page?: number; perPage?: number; total?: number; }; } export interface ApiError { error: { code: string; message: string; details?: Record<string, unknown>; }; } export type ApiResult<T> = ApiResponse<T> | ApiError; // Standard pagination params export interface PaginationParams { page?: number; perPage?: number; sortBy?: string; sortOrder?: "asc" | "desc"; } // Standard filter params export interface FilterParams { search?: string; startDate?: string; endDate?: string; status?: string; }
Shared Zod Schemas
// packages/contracts/src/schemas/user.schema.ts import { z } from "zod"; export const SharedUserSchema = z.object({ id: z.string().uuid(), email: z.string().email(), displayName: z.string().min(1).max(100), avatarUrl: z.string().url().optional(), provider: z.enum(["firebase", "supabase", "identity-platform"]), metadata: z.object({ createdAt: z.string().datetime(), lastLoginAt: z.string().datetime(), source: z.string(), }), }); export type SharedUser = z.infer<typeof SharedUserSchema>; // packages/contracts/src/schemas/pagination.schema.ts import { z } from "zod"; export const PaginationSchema = z.object({ page: z.coerce.number().int().positive().default(1), perPage: z.coerce.number().int().positive().max(100).default(20), sortBy: z.string().optional(), sortOrder: z.enum(["asc", "desc"]).default("desc"), }); export const FilterSchema = z.object({ search: z.string().optional(), startDate: z.string().datetime().optional(), endDate: z.string().datetime().optional(), status: z.string().optional(), });
Shared Event Schemas (for inter-app communication)
// packages/contracts/src/events/index.ts import { z } from "zod"; export const BaseEventSchema = z.object({ id: z.string().uuid(), type: z.string(), source: z.string(), // app name that emitted the event timestamp: z.string().datetime(), version: z.literal("1.0"), payload: z.record(z.unknown()), }); export type BaseEvent = z.infer<typeof BaseEventSchema>; // Example domain events export const UserCreatedEventSchema = BaseEventSchema.extend({ type: z.literal("user.created"), payload: z.object({ userId: z.string(), email: z.string().email(), provider: z.string(), }), }); export const EntityUpdatedEventSchema = BaseEventSchema.extend({ type: z.literal("entity.updated"), payload: z.object({ entityId: z.string(), changes: z.record(z.unknown()), updatedBy: z.string(), }), }); // Event type registry — add new events here export const EventSchemaRegistry = { "user.created": UserCreatedEventSchema, "entity.updated": EntityUpdatedEventSchema, } as const; export type EventType = keyof typeof EventSchemaRegistry;
How Apps Consume Contracts
In any app's package.json: { "dependencies": { "@repo/contracts": "workspace:*" } } Usage: import { SharedUserSchema, type SharedUser } from "@repo/contracts/schemas"; import { PaginationSchema } from "@repo/contracts/schemas"; import type { ApiResponse, ApiError } from "@repo/contracts";
Part 3 — API-First Design with OpenAPI
Every app MUST define its public API as an OpenAPI 3.1 spec BEFORE implementing the endpoints. The spec lives in packages/api-specs/.
Spec Structure
# packages/api-specs/app-one.openapi.yaml openapi: "3.1.0" info: title: App One API version: "1.0.0" description: Public API for App One contact: name: Team servers: - url: https://app-one.vercel.app/api description: Production - url: http://localhost:3001/api description: Local development paths: /entities: get: operationId: listEntities summary: List all entities for the authenticated user tags: [Entities] security: - BearerAuth: [] parameters: - $ref: "#/components/parameters/Page" - $ref: "#/components/parameters/PerPage" - $ref: "#/components/parameters/Search" responses: "200": description: Paginated list of entities content: application/json: schema: $ref: "#/components/schemas/EntityListResponse" "401": $ref: "#/components/responses/Unauthorized" post: operationId: createEntity summary: Create a new entity tags: [Entities] security: - BearerAuth: [] requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/CreateEntityInput" responses: "201": description: Entity created content: application/json: schema: $ref: "#/components/schemas/EntityResponse" "400": $ref: "#/components/responses/ValidationError" "401": $ref: "#/components/responses/Unauthorized" /entities/{id}: get: operationId: getEntity summary: Get a single entity tags: [Entities] security: - BearerAuth: [] parameters: - name: id in: path required: true schema: type: string format: uuid responses: "200": description: Entity details content: application/json: schema: $ref: "#/components/schemas/EntityResponse" "404": $ref: "#/components/responses/NotFound" components: securitySchemes: BearerAuth: type: http scheme: bearer bearerFormat: JWT parameters: Page: name: page in: query schema: type: integer default: 1 PerPage: name: perPage in: query schema: type: integer default: 20 maximum: 100 Search: name: search in: query schema: type: string schemas: Entity: type: object required: [id, name, createdAt] properties: id: type: string format: uuid name: type: string description: type: string status: type: string enum: [active, archived] createdAt: type: string format: date-time updatedAt: type: string format: date-time CreateEntityInput: type: object required: [name] properties: name: type: string minLength: 1 maxLength: 200 description: type: string maxLength: 2000 EntityResponse: type: object properties: data: $ref: "#/components/schemas/Entity" EntityListResponse: type: object properties: data: type: array items: $ref: "#/components/schemas/Entity" meta: $ref: "#/components/schemas/PaginationMeta" PaginationMeta: type: object properties: page: type: integer perPage: type: integer total: type: integer responses: Unauthorized: description: Authentication required content: application/json: schema: type: object properties: error: type: object properties: code: type: string example: UNAUTHORIZED message: type: string example: Authentication required NotFound: description: Resource not found content: application/json: schema: type: object properties: error: type: object properties: code: type: string example: NOT_FOUND message: type: string ValidationError: description: Input validation failed content: application/json: schema: type: object properties: error: type: object properties: code: type: string example: VALIDATION_ERROR message: type: string details: type: object
Spec Validation
Before generating an SDK, always validate the spec: npx @redocly/cli lint packages/api-specs/app-one.openapi.yaml
Part 4 — Auto-Generated Typed SDKs
Generate a typed TypeScript client from each OpenAPI spec so apps can call each other with full type safety.
SDK Package Setup
// packages/sdk/package.json { "name": "@repo/sdk", "version": "0.1.0", "private": true, "exports": { "./app-one": { "import": "./src/generated/app-one/index.ts", "types": "./src/generated/app-one/index.ts" }, "./app-two": { "import": "./src/generated/app-two/index.ts", "types": "./src/generated/app-two/index.ts" } }, "scripts": { "generate": "pnpm generate:app-one && pnpm generate:app-two", "generate:app-one": "openapi-typescript ../api-specs/app-one.openapi.yaml -o src/generated/app-one/schema.d.ts", "generate:app-two": "openapi-typescript ../api-specs/app-two.openapi.yaml -o src/generated/app-two/schema.d.ts" }, "devDependencies": { "openapi-typescript": "^7.0.0", "openapi-fetch": "^0.10.0" } }
SDK Client Wrapper
// packages/sdk/src/generated/app-one/index.ts import createClient from "openapi-fetch"; import type { paths } from "./schema"; export function createAppOneClient(options: { baseUrl: string; token: string; }) { return createClient<paths>({ baseUrl: options.baseUrl, headers: { Authorization: `Bearer ${options.token}`, }, }); } // Re-export types for convenience export type { paths } from "./schema";
Usage in Another App
// apps/app-two/src/lib/app-one-client.ts import { createAppOneClient } from "@repo/sdk/app-one"; const appOneClient = createAppOneClient({ baseUrl: process.env.APP_ONE_API_URL!, token: process.env.CROSS_APP_TOKEN!, }); // Fully typed — IDE autocomplete works const { data, error } = await appOneClient.GET("/entities", { params: { query: { page: 1, perPage: 10 } }, }); if (data) { // data.data is Entity[], data.meta is PaginationMeta — all typed }
SDK Generation Pipeline
Add to turbo.json: { "generate:sdk": { "dependsOn": ["^build"], "inputs": ["packages/api-specs/**/*.yaml"], "outputs": ["packages/sdk/src/generated/**"] } } Run: pnpm turbo generate:sdk
Strategy: JWT Forwarding with Shared Verification
All apps share the same auth provider (Firebase or Supabase Auth). When app-two calls app-one's API, it forwards the user's JWT. App-one verifies the token using the same provider.
Shared Auth Package
// packages/auth/package.json { "name": "@repo/auth", "version": "0.1.0", "private": true, "main": "./dist/index.js", "types": "./dist/index.d.ts", "scripts": { "build": "tsup src/index.ts --format esm --dts" } } // packages/auth/src/index.ts export { verifyToken, type TokenPayload } from "./verify"; export { createCrossAppToken } from "./cross-app"; export { authMiddleware } from "./middleware";
Token Verification (stack-agnostic)
// packages/auth/src/verify.ts import type { CrossAppToken } from "@repo/contracts"; export interface TokenPayload { sub: string; email: string; iss: string; permissions: string[]; } type AuthProvider = "firebase" | "supabase"; export async function verifyToken( token: string, provider: AuthProvider ): Promise<TokenPayload> { if (provider === "firebase") { // Dynamic import to avoid bundling both SDKs const { getAuth } = await import("firebase-admin/auth"); const decoded = await getAuth().verifyIdToken(token); return { sub: decoded.uid, email: decoded.email ?? "", iss: "firebase", permissions: (decoded.permissions as string[]) ?? [], }; } if (provider === "supabase") { const { createClient } = await import("@supabase/supabase-js"); const supabase = createClient( process.env.SUPABASE_URL!, process.env.SUPABASE_ANON_KEY! ); const { data, error } = await supabase.auth.getUser(token); if (error || !data.user) throw new Error("Invalid token"); return { sub: data.user.id, email: data.user.email ?? "", iss: "supabase", permissions: (data.user.app_metadata?.permissions as string[]) ?? [], }; } throw new Error(`Unsupported auth provider: ${provider}`); }
Cross-App Token Generation
// packages/auth/src/cross-app.ts import { SignJWT, jwtVerify } from "jose"; const SECRET = new TextEncoder().encode( process.env.CROSS_APP_SECRET! // Shared secret between apps (32+ chars) ); export async function createCrossAppToken(payload: { sub: string; email: string; sourceApp: string; targetApps: string[]; permissions: string[]; }): Promise<string> { return new SignJWT({ sub: payload.sub, email: payload.email, iss: payload.sourceApp, aud: payload.targetApps, permissions: payload.permissions, }) .setProtectedHeader({ alg: "HS256" }) .setIssuedAt() .setExpirationTime("5m") // Short-lived for security .sign(SECRET); } export async function verifyCrossAppToken( token: string, expectedAudience: string ) { const { payload } = await jwtVerify(token, SECRET, { audience: expectedAudience, }); return payload; }
Auth Middleware (reusable across apps)
// packages/auth/src/middleware.ts import { verifyToken, type TokenPayload } from "./verify"; import { verifyCrossAppToken } from "./cross-app"; import type { NextRequest } from "next/server"; type AuthProvider = "firebase" | "supabase"; export function authMiddleware(options: { provider: AuthProvider; appName: string; allowCrossApp?: boolean; }) { return async function (request: NextRequest): Promise<TokenPayload | null> { const authHeader = request.headers.get("Authorization"); if (!authHeader?.startsWith("Bearer ")) return null; const token = authHeader.slice(7); // Try standard auth first try { return await verifyToken(token, options.provider); } catch { // If standard auth fails and cross-app is enabled, try cross-app token if (options.allowCrossApp) { try { const payload = await verifyCrossAppToken(token, options.appName); return { sub: payload.sub as string, email: (payload.email as string) ?? "", iss: payload.iss ?? "unknown", permissions: (payload.permissions as string[]) ?? [], }; } catch { return null; } } return null; } }; }
Pattern A: Shared Database Instance (Same Supabase/Firestore)
When multiple apps share the same database, use schema-based isolation: -- Supabase: each app gets its own schema CREATE SCHEMA IF NOT EXISTS app_one; CREATE SCHEMA IF NOT EXISTS app_two; CREATE SCHEMA IF NOT EXISTS shared; -- cross-app tables live here -- Shared users table (single source of truth) CREATE TABLE shared.users ( id UUID PRIMARY KEY DEFAULT gen_random_uuid(), email TEXT UNIQUE NOT NULL, display_name TEXT NOT NULL, avatar_url TEXT, provider TEXT NOT NULL, source_app TEXT NOT NULL, created_at TIMESTAMPTZ DEFAULT now(), updated_at TIMESTAMPTZ DEFAULT now() ); -- App-specific tables use their own schema CREATE TABLE app_one.entities ( id UUID PRIMARY KEY DEFAULT gen_random_uuid(), user_id UUID REFERENCES shared.users(id), name TEXT NOT NULL, created_at TIMESTAMPTZ DEFAULT now() ); -- RLS: each app can only see data within its schema + shared ALTER TABLE app_one.entities ENABLE ROW LEVEL SECURITY; CREATE POLICY "users see own entities" ON app_one.entities FOR ALL USING (user_id = auth.uid()); For Firestore, use top-level collection prefixes: /shared/users/{userId} /app-one/entities/{entityId} /app-two/items/{itemId}
Pattern B: Separate Database Instances
When apps have their own database, communication happens via API calls using the generated SDK: // app-two needs data from app-one import { createAppOneClient } from "@repo/sdk/app-one"; import { createCrossAppToken } from "@repo/auth"; async function getDataFromAppOne(userId: string) { const token = await createCrossAppToken({ sub: userId, email: "user@example.com", sourceApp: "app-two", targetApps: ["app-one"], permissions: ["entities:read"], }); const client = createAppOneClient({ baseUrl: process.env.APP_ONE_API_URL!, token, }); return client.GET("/entities"); }
Decision Rule
ScenarioUse shared DBUse separate DBs + APIApps share user accountsyes-Apps share business entitiesyes-Apps are independently deployable-yesApps may be split into separate repos later-yesReal-time sync needed between appsyes-Apps have different scaling requirements-yesRegulatory isolation required-yes
Part 7 — MCP Server Scaffolding
Each app exposes a full MCP server that allows AI agents to interact with its capabilities.
MCP Server Structure
mcp-servers/ ├── app-one-mcp/ │ ├── package.json │ ├── tsconfig.json │ ├── src/ │ │ ├── index.ts # Server entry point │ │ ├── tools/ # One file per tool │ │ │ ├── list-entities.ts │ │ │ ├── create-entity.ts │ │ │ ├── get-entity.ts │ │ │ └── search-entities.ts │ │ ├── resources/ # Exposed data resources │ │ │ └── entity-schema.ts │ │ └── auth.ts # Auth handling for MCP │ └── mcp.json # MCP manifest
MCP Server Entry Point Template
// mcp-servers/app-one-mcp/src/index.ts import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js"; import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js"; import { listEntitiesTool } from "./tools/list-entities.js"; import { createEntityTool } from "./tools/create-entity.js"; import { getEntityTool } from "./tools/get-entity.js"; import { searchEntitiesTool } from "./tools/search-entities.js"; const server = new McpServer({ name: "app-one-mcp", version: "1.0.0", }); // Register tools listEntitiesTool(server); createEntityTool(server); getEntityTool(server); searchEntitiesTool(server); // Start server const transport = new StdioServerTransport(); await server.connect(transport);
MCP Tool Template
// mcp-servers/app-one-mcp/src/tools/list-entities.ts import { z } from "zod"; import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js"; import { createAppOneClient } from "@repo/sdk/app-one"; const ParamsSchema = z.object({ page: z.number().int().positive().default(1).describe("Page number"), perPage: z.number().int().positive().max(100).default(20).describe("Items per page"), search: z.string().optional().describe("Search term to filter entities"), }); export function listEntitiesTool(server: McpServer) { server.tool( "list-entities", "List entities from App One with pagination and optional search", ParamsSchema.shape, async (params) => { const validated = ParamsSchema.parse(params); const client = createAppOneClient({ baseUrl: process.env.APP_ONE_API_URL!, token: process.env.APP_ONE_SERVICE_TOKEN!, }); const { data, error } = await client.GET("/entities", { params: { query: validated }, }); if (error) { return { content: [{ type: "text", text: `Error: ${JSON.stringify(error)}` }], isError: true, }; } return { content: [ { type: "text", text: JSON.stringify(data, null, 2), }, ], }; } ); }
MCP Tool for Cross-App Operations
// mcp-servers/app-one-mcp/src/tools/create-entity.ts import { z } from "zod"; import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js"; import { createAppOneClient } from "@repo/sdk/app-one"; import { CreateEntityInputSchema } from "@repo/contracts/schemas"; export function createEntityTool(server: McpServer) { server.tool( "create-entity", "Create a new entity in App One", { name: z.string().min(1).max(200).describe("Entity name"), description: z.string().max(2000).optional().describe("Entity description"), }, async (params) => { // Validate against shared contract const validated = CreateEntityInputSchema.parse(params); const client = createAppOneClient({ baseUrl: process.env.APP_ONE_API_URL!, token: process.env.APP_ONE_SERVICE_TOKEN!, }); const { data, error } = await client.POST("/entities", { body: validated, }); if (error) { return { content: [{ type: "text", text: `Error creating entity: ${JSON.stringify(error)}` }], isError: true, }; } return { content: [ { type: "text", text: `Entity created successfully:\n${JSON.stringify(data, null, 2)}`, }, ], }; } ); }
MCP Manifest
// mcp-servers/app-one-mcp/mcp.json { "name": "app-one-mcp", "version": "1.0.0", "description": "MCP server for App One — manage entities, search, and CRUD operations", "tools": [ { "name": "list-entities", "description": "List entities with pagination and search" }, { "name": "create-entity", "description": "Create a new entity" }, { "name": "get-entity", "description": "Get entity details by ID" }, { "name": "search-entities", "description": "Full-text search across entities" } ], "env": { "APP_ONE_API_URL": { "description": "Base URL of App One's API", "required": true }, "APP_ONE_SERVICE_TOKEN": { "description": "Service token for authenticating MCP server to App One", "required": true } } }
MCP Server Package.json
// mcp-servers/app-one-mcp/package.json { "name": "app-one-mcp", "version": "1.0.0", "private": true, "type": "module", "main": "dist/index.js", "scripts": { "build": "tsup src/index.ts --format esm", "dev": "tsx watch src/index.ts", "start": "node dist/index.js" }, "dependencies": { "@modelcontextprotocol/sdk": "^1.0.0", "@repo/sdk": "workspace:*", "@repo/contracts": "workspace:*", "@repo/auth": "workspace:*", "zod": "^3.23.0" }, "devDependencies": { "tsup": "^8.0.0", "tsx": "^4.0.0", "typescript": "^5.4.0" } }
Registering MCP Servers in Claude Desktop / OpenClaw
// claude_desktop_config.json or openclaw config { "mcpServers": { "app-one": { "command": "node", "args": ["./mcp-servers/app-one-mcp/dist/index.js"], "env": { "APP_ONE_API_URL": "http://localhost:3001/api", "APP_ONE_SERVICE_TOKEN": "${APP_ONE_SERVICE_TOKEN}" } }, "app-two": { "command": "node", "args": ["./mcp-servers/app-two-mcp/dist/index.js"], "env": { "APP_TWO_API_URL": "http://localhost:3002/api", "APP_TWO_SERVICE_TOKEN": "${APP_TWO_SERVICE_TOKEN}" } } } }
Pattern 1: Synchronous API Call (via SDK)
Use when: app-two needs data from app-one in real-time, within a single request lifecycle. // Already shown in Part 4 — use @repo/sdk import { createAppOneClient } from "@repo/sdk/app-one";
Pattern 2: Event-Based (Webhook/Pub-Sub)
Use when: apps need to react to changes in other apps asynchronously. // packages/contracts/src/events/webhook.ts import type { BaseEvent } from "./index"; export interface WebhookConfig { url: string; secret: string; events: string[]; // event types to subscribe to } // Emit event to registered webhooks export async function emitEvent( event: BaseEvent, webhooks: WebhookConfig[] ): Promise<void> { const relevant = webhooks.filter((wh) => wh.events.includes(event.type) || wh.events.includes("*") ); await Promise.allSettled( relevant.map((wh) => fetch(wh.url, { method: "POST", headers: { "Content-Type": "application/json", "X-Webhook-Secret": wh.secret, "X-Event-Type": event.type, "X-Event-ID": event.id, }, body: JSON.stringify(event), }) ) ); }
Pattern 3: Shared Database Query
Use when: apps share a database and need access to the same tables. // Both apps import from @repo/contracts for type safety import { SharedUserSchema } from "@repo/contracts/schemas"; // App-one writes await supabase.schema("shared").from("users").insert(newUser); // App-two reads const { data } = await supabase.schema("shared").from("users").select("*"); const users = data.map((u) => SharedUserSchema.parse(u));
Scaffold a New App in the Monorepo
When the user says "add a new app," follow this sequence: # 1. Create the app directory mkdir -p apps/app-new # 2. Scaffold based on detected framework preference # For Next.js: cd apps/app-new && npx create-next-app@latest . --typescript --tailwind --app --eslint --src-dir # 3. Add shared dependencies cd apps/app-new pnpm add @repo/contracts @repo/auth @repo/sdk # 4. Create the OpenAPI spec cp packages/api-specs/_template.openapi.yaml packages/api-specs/app-new.openapi.yaml # 5. Generate the SDK pnpm --filter @repo/sdk generate:app-new # 6. Scaffold the MCP server mkdir -p mcp-servers/app-new-mcp/src/tools # ... generate boilerplate files
Scaffold a New Shared Contract
# Add a new entity type to contracts # 1. Create the type file touch packages/contracts/src/types/new-entity.ts # 2. Create the schema file touch packages/contracts/src/schemas/new-entity.schema.ts # 3. Export from index files # 4. Rebuild contracts pnpm --filter @repo/contracts build
Scaffold a New MCP Tool
# Add a new tool to an existing MCP server touch mcp-servers/app-one-mcp/src/tools/new-operation.ts # Follow the tool template from Part 7 # Register in index.ts # Update mcp.json manifest
Part 10 — Validation Checklist
Before considering the integration work complete, verify:
Contracts
All shared types are in @repo/contracts Zod schemas exist for every shared type No duplicate type definitions across apps Contracts package builds without errors
API Specs
OpenAPI spec exists for every app that exposes an API Spec passes @redocly/cli lint All shared schemas reference @repo/contracts types Error responses follow the standard ApiError format
SDKs
SDK generated from latest specs SDK builds without TypeScript errors Each app that calls another uses the SDK (not raw fetch)
Authentication
All apps use @repo/auth for token verification Cross-app tokens are short-lived (5 minutes max) CROSS_APP_SECRET is at least 32 characters Auth middleware handles both standard and cross-app tokens
MCP Servers
Each app has a corresponding MCP server Every public API endpoint has a corresponding MCP tool MCP tools use @repo/sdk (not direct API calls) MCP tools validate input with Zod schemas from @repo/contracts MCP manifest (mcp.json) is up to date
Monorepo
turbo.json has correct dependency graph pnpm-workspace.yaml includes all directories pnpm turbo build succeeds with no errors pnpm turbo typecheck succeeds with no errors
Best Practices (DO)
ALWAYS start by surveying the monorepo structure and existing packages ALWAYS put shared types in @repo/contracts, never duplicate across apps ALWAYS write OpenAPI specs BEFORE implementing endpoints ALWAYS generate SDKs from specs (never hand-write API clients) ALWAYS use the shared auth package for token verification ALWAYS scaffold MCP servers using the SDK (not raw fetch) ALWAYS validate MCP tool inputs with Zod schemas from contracts Use short-lived cross-app tokens (5 min TTL) Use schema-based isolation when sharing a database Keep MCP tools focused — one tool per operation Version event schemas (include version: "1.0" in every event)
Anti-Patterns (AVOID)
NEVER duplicate type definitions across apps — use @repo/contracts NEVER hand-write API clients — always generate from OpenAPI specs NEVER use long-lived tokens for cross-app communication NEVER give one app direct database access to another app's schema NEVER create circular dependencies between packages NEVER skip OpenAPI spec validation before SDK generation NEVER put business logic in the contracts package (types and schemas only) NEVER create MCP tools that bypass authentication NEVER hardcode base URLs — always use environment variables
Safety Rules
NEVER read or modify .env, .env.local, or any credential file directly All env var references are in generated code via process.env.* NEVER commit CROSS_APP_SECRET or any service tokens to git NEVER expose service-to-service tokens in client-side code NEVER create MCP tools that delete data without confirmation parameters NEVER auto-execute webhooks without verifying the secret Cross-app tokens MUST have an aud (audience) claim restricting which app can use them
Category context
Code helpers, APIs, CLIs, browser automation, testing, and developer operations.
Source: Tencent SkillHub
Largest current source with strong distribution and engagement signals.
Package contents
Included in package
1 Docs1 Config
- SKILL.md
- claw.json