القائمة
Guide for adding new MCP tools with consistent patterns for schemas, tool definitions, registry updates, and Better Auth integration
يُحدَّد Prompt الذي يراجع المصدر أولًا بشكل افتراضي. يمكنك التبديل إلى أمر مباشر أو تنزيل نسخة محلية.
اقرأ SKILL.md وأي ملفات مرافقة يعرضها SkillsMP قبل أن تقرر التثبيت.
التثبيت باستخدام Codex أو Claude انسخ هذا Prompt والصقه في Codex أو Claude أو مساعد آخر ليراجع صفحة Skill ويثبّتها لك.
يتجاوز الأمر المباشر Prompt المخصّص للمراجعة. افحص المصدر قبل تشغيله.
npx skills add https://github.com/decocms/studio --skill add-mcp-toolsيبقى الأمر في سطر واحد. مرّر أفقيًا لمراجعته كاملًا قبل النسخ.
تفضّل نسخة محلية؟ نزّل الملفات المتاحة حاليًا لدى SkillsMP.
استنادا إلى تصنيف SOC المهني
عرض SKILL.md
| name | add-mcp-tools |
| description | Guide for adding new MCP tools with consistent patterns for schemas, tool definitions, registry updates, and Better Auth integration |
This guide documents the pattern for adding new MCP tools to Studio codebase. Follow this checklist to ensure consistency with existing tools.
MCP tools are exposed via the Model Context Protocol and allow programmatic management of resources. Each tool follows a consistent pattern with:
defineTool for automatic tracing, metrics, and audit loggingctx.access.check()ctx.boundAuthWhen adding a new domain of tools (e.g., apiKeys, webhooks, secrets), create the following structure:
apps/api/src/tools/<domain>/
├── schema.ts # Zod schemas for entities and operations
├── create.ts # <DOMAIN>_CREATE tool
├── list.ts # <DOMAIN>_LIST tool
├── update.ts # <DOMAIN>_UPDATE tool
├── delete.ts # <DOMAIN>_DELETE tool
└── index.ts # Barrel export
schema.ts)Define Zod schemas for:
// apps/api/src/tools/<domain>/schema.ts
{ z } ;
= z.({
: z.(),
: z.(),
: z.([z.(), z.()]),
});
= z.< >;
= z.({
: z.().().(),
});
= z.({
: ,
});
= z.({
});
= z.({
: z.(),
});
= z.({
: z.(),
});
= z.({
: ,
});
= z.({
: z.(),
});
= z.({
: z.(),
: z.(),
});
Each tool file follows this pattern:
// apps/api/src/tools/<domain>/create.ts
import { defineTool } from "../../core/define-tool";
import { getUserId, requireAuth, requireOrganization } from "../../core/studio-context";
import { MyCreateInputSchema, MyCreateOutputSchema } from "./schema";
export const MY_DOMAIN_CREATE = defineTool({
name: "MY_DOMAIN_CREATE",
description: "Create a new resource",
inputSchema: MyCreateInputSchema,
outputSchema: MyCreateOutputSchema,
handler: async (input, ctx) => {
// 1. Require authentication
requireAuth(ctx);
// 2. Require organization (if org-scoped)
const organization = requireOrganization(ctx);
// 3. Check authorization
await ctx.access.check();
// 4. Get user ID
const userId = getUserId(ctx);
if (!userId) {
throw new Error("User ID required");
}
// 5. Perform operation
// Option A: Use ctx.boundAuth for Better Auth operations
const result = await ctx.boundAuth.myDomain.create({ ... });
// Option B: Use ctx.storage for custom storage operations
const result = await ctx.storage.myDomain.create({ ... });
// 6. Return result
return { item: result };
},
});
index.ts)// apps/api/src/tools/<domain>/index.ts
export { MY_DOMAIN_CREATE } from "./create";
export { MY_DOMAIN_LIST } from "./list";
export { MY_DOMAIN_UPDATE } from "./update";
export { MY_DOMAIN_DELETE } from "./delete";
// Export schemas for external use
export * from "./schema";
registry.ts)Add tool names and metadata:
// apps/api/src/tools/registry.ts
// 1. Add to ToolCategory type (if new category)
export type ToolCategory = "Organizations" | "Connections" | "My Domain";
// 2. Add to ALL_TOOL_NAMES array
const ALL_TOOL_NAMES = [
// ... existing tools
"MY_DOMAIN_CREATE",
"MY_DOMAIN_LIST",
"MY_DOMAIN_UPDATE",
"MY_DOMAIN_DELETE",
] as const;
// 3. Add to MANAGEMENT_TOOLS array
export const MANAGEMENT_TOOLS: ToolMetadata[] = [
// ... existing tools
{
name: "MY_DOMAIN_CREATE",
description: "Create resource",
category: "My Domain",
},
{
name: "MY_DOMAIN_LIST",
description: "List resources",
category: "My Domain",
},
{
name: "MY_DOMAIN_UPDATE",
description: "Update resource",
category: "My Domain",
},
{
name: "MY_DOMAIN_DELETE",
description: "Delete resource",
category: "My Domain",
dangerous: true,
},
];
// 4. Add to TOOL_LABELS
const TOOL_LABELS: Record<ToolName, string> = {
// ... existing labels
MY_DOMAIN_CREATE: "Create resource",
MY_DOMAIN_LIST: "List resources",
MY_DOMAIN_UPDATE: "Update resource",
MY_DOMAIN_DELETE: "Delete resource",
};
// 5. Update getToolsByCategory if new category
export function getToolsByCategory() {
const grouped: Record<string, ToolMetadata[]> = {
Organizations: [],
Connections: [],
"My Domain": [], // Add new category
};
// ...
}
tools/index.ts)// apps/api/src/tools/index.ts
import * as MyDomainTools from "./myDomain";
export { MyDomainTools };
export const ALL_TOOLS = [
// ... existing tools
MyDomainTools.MY_DOMAIN_CREATE,
MyDomainTools.MY_DOMAIN_LIST,
MyDomainTools.MY_DOMAIN_UPDATE,
MyDomainTools.MY_DOMAIN_DELETE,
] as const satisfies { name: ToolName }[];
// apps/api/src/auth/index.ts
apiKey({
permissions: {
defaultPermissions: {
self: [
// ... existing permissions
"MY_DOMAIN_LIST", // Read access by default
// Note: CREATE, UPDATE, DELETE usually NOT default
],
},
},
}),
If your tools wrap Better Auth APIs, you need to:
a. Add types to studio-context.ts:
// apps/api/src/core/studio-context.ts
// Add return types
export type MyDomainCreateResult = Awaited<
ReturnType<BetterAuthApi["createMyDomain"]>
>;
// ... other types
// Add to BoundAuthClient interface
export interface BoundAuthClient {
// ... existing methods
myDomain: {
create(data: { ... }): Promise<MyDomainCreateResult>;
list(): Promise<MyDomainListResult>;
update(data: { ... }): Promise<MyDomainUpdateResult>;
delete(id: string): Promise<void>;
};
}
b. Implement in context-factory.ts:
// apps/api/src/core/context-factory.ts
function createBoundAuthClient(ctx: AuthContext): BoundAuthClient {
return {
// ... existing implementations
myDomain: {
create: async (data) => {
return auth.api.createMyDomain({ headers, body: data });
},
list: async () => {
return auth.api.listMyDomain({ headers });
},
update: async (data) => {
return auth.api.updateMyDomain({ headers, body: data });
},
delete: async (id) => {
await auth.api.deleteMyDomain({ headers, body: { id } });
},
},
};
}
// Always in this order:
requireAuth(ctx); // 1. Must be authenticated
const org = requireOrganization(ctx); // 2. Must have org context (if org-scoped)
await ctx.access.check(); // 3. Must have permission for this tool
// Throw descriptive errors
if (!result) {
throw new Error(`Resource not found: ${id}`);
}
if (result.organizationId !== organization.id) {
throw new Error("Resource not found in organization");
}
For sensitive data (like API key values):
// Only return sensitive data at creation time
export const CreateOutputSchema = z.object({
id: z.string(),
secretValue: z.string(), // Only here!
});
// Never return in list/get
export const EntitySchema = z.object({
id: z.string(),
// NO secretValue field
});
Create test files alongside tool files:
apps/api/src/tools/<domain>/
├── create.test.ts
├── list.test.ts
├── update.test.ts
└── delete.test.ts
Use the existing test patterns from apps/api/src/tools/connection/ as reference.
await ctx.access.check() - Always check authorizationregistry.ts AND tools/index.tsDOMAIN_ACTION pattern (e.g., API_KEY_CREATE)auth/index.ts if users should have access by defaultrequireOrganization(ctx) for org-scoped resources