MCP Server 2.0 (#452)
* MCP Server 2.0 - Updated application version from 2.23.14 to 2.24.0 in package.json. - MCP Server improved with new features - Migrated functionality from Dev Tools to MCP Server - Improved getMonitoringProvider not to crash application when misconfigured
This commit is contained in:
Giancarlo Buomprisco
committed by
GitHub
GitHub
parent
059408a70a
commit
f3ac595d06
308
.claude/skills/service-builder/SKILL.md
Normal file
308
.claude/skills/service-builder/SKILL.md
Normal file
@@ -0,0 +1,308 @@
|
||||
---
|
||||
name: service-builder
|
||||
description: Build pure, interface-agnostic services with injected dependencies. Use when creating business logic that must work across server actions, MCP tools, CLI commands, or tests. Invoke with /service-builder.
|
||||
---
|
||||
|
||||
# Service Builder
|
||||
|
||||
You are an expert at building pure, testable services that are decoupled from their callers.
|
||||
|
||||
## North Star
|
||||
|
||||
**Every service is decoupled from its interface (I/O).** A service takes plain data in, does work, and returns plain data out. It has no knowledge of whether it was called from an MCP tool, a server action, a CLI command, a route handler, or a test. The caller is a thin adapter that resolves dependencies and delegates.
|
||||
|
||||
## Workflow
|
||||
|
||||
When asked to create a service, follow these steps:
|
||||
|
||||
### Step 1: Define the Contract
|
||||
|
||||
Start with the input/output types. These are plain TypeScript — no framework types.
|
||||
|
||||
```typescript
|
||||
// _lib/schemas/project.schema.ts
|
||||
import { z } from 'zod';
|
||||
|
||||
export const CreateProjectSchema = z.object({
|
||||
name: z.string().min(1),
|
||||
accountId: z.string().uuid(),
|
||||
});
|
||||
|
||||
export type CreateProjectInput = z.infer<typeof CreateProjectSchema>;
|
||||
|
||||
export interface Project {
|
||||
id: string;
|
||||
name: string;
|
||||
account_id: string;
|
||||
created_at: string;
|
||||
}
|
||||
```
|
||||
|
||||
### Step 2: Build the Service
|
||||
|
||||
The service receives all dependencies through its constructor. It never imports framework-specific modules (`getSupabaseServerClient`, `getLogger`, `revalidatePath`, etc.).
|
||||
|
||||
```typescript
|
||||
// _lib/server/project.service.ts
|
||||
import type { SupabaseClient } from '@supabase/supabase-js';
|
||||
|
||||
import type { CreateProjectInput, Project } from '../schemas/project.schema';
|
||||
|
||||
export function createProjectService(client: SupabaseClient) {
|
||||
return new ProjectService(client);
|
||||
}
|
||||
|
||||
class ProjectService {
|
||||
constructor(private readonly client: SupabaseClient) {}
|
||||
|
||||
async create(data: CreateProjectInput): Promise<Project> {
|
||||
const { data: result, error } = await this.client
|
||||
.from('projects')
|
||||
.insert({
|
||||
name: data.name,
|
||||
account_id: data.accountId,
|
||||
})
|
||||
.select()
|
||||
.single();
|
||||
|
||||
if (error) throw error;
|
||||
|
||||
return result;
|
||||
}
|
||||
|
||||
async list(accountId: string): Promise<Project[]> {
|
||||
const { data, error } = await this.client
|
||||
.from('projects')
|
||||
.select('*')
|
||||
.eq('account_id', accountId)
|
||||
.order('created_at', { ascending: false });
|
||||
|
||||
if (error) throw error;
|
||||
|
||||
return data;
|
||||
}
|
||||
|
||||
async delete(projectId: string): Promise<void> {
|
||||
const { error } = await this.client
|
||||
.from('projects')
|
||||
.delete()
|
||||
.eq('id', projectId);
|
||||
|
||||
if (error) throw error;
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Step 3: Write Thin Adapters
|
||||
|
||||
Each interface is a thin adapter — it resolves dependencies, calls the service, and handles interface-specific concerns (revalidation, redirects, MCP formatting, CLI output).
|
||||
|
||||
**Server Action adapter:**
|
||||
|
||||
```typescript
|
||||
// _lib/server/server-actions.ts
|
||||
'use server';
|
||||
|
||||
import { enhanceAction } from '@kit/next/actions';
|
||||
import { getLogger } from '@kit/shared/logger';
|
||||
import { getSupabaseServerClient } from '@kit/supabase/server-client';
|
||||
import { revalidatePath } from 'next/cache';
|
||||
|
||||
import { CreateProjectSchema } from '../schemas/project.schema';
|
||||
import { createProjectService } from './project.service';
|
||||
|
||||
export const createProjectAction = enhanceAction(
|
||||
async function (data, user) {
|
||||
const logger = await getLogger();
|
||||
logger.info({ name: 'create-project', userId: user.id }, 'Creating project');
|
||||
|
||||
const client = getSupabaseServerClient();
|
||||
const service = createProjectService(client);
|
||||
const result = await service.create(data);
|
||||
|
||||
revalidatePath('/home/[account]/projects');
|
||||
|
||||
return { success: true, data: result };
|
||||
},
|
||||
{
|
||||
auth: true,
|
||||
schema: CreateProjectSchema,
|
||||
},
|
||||
);
|
||||
```
|
||||
|
||||
**Route Handler adapter:**
|
||||
|
||||
```typescript
|
||||
// app/api/projects/route.ts
|
||||
import { enhanceRouteHandler } from '@kit/next/routes';
|
||||
import { getSupabaseServerClient } from '@kit/supabase/server-client';
|
||||
import { NextResponse } from 'next/server';
|
||||
|
||||
import { CreateProjectSchema } from '../_lib/schemas/project.schema';
|
||||
import { createProjectService } from '../_lib/server/project.service';
|
||||
|
||||
export const POST = enhanceRouteHandler(
|
||||
async function ({ body, user }) {
|
||||
const client = getSupabaseServerClient();
|
||||
const service = createProjectService(client);
|
||||
const result = await service.create(body);
|
||||
|
||||
return NextResponse.json(result);
|
||||
},
|
||||
{
|
||||
auth: true,
|
||||
schema: CreateProjectSchema,
|
||||
},
|
||||
);
|
||||
```
|
||||
|
||||
**MCP Tool adapter:**
|
||||
|
||||
```typescript
|
||||
// mcp/tools/kit_project_create.ts
|
||||
import { createProjectService } from '../../_lib/server/project.service';
|
||||
|
||||
export const kit_project_create: McpToolHandler = async (input, context) => {
|
||||
const client = context.getSupabaseClient();
|
||||
const service = createProjectService(client);
|
||||
|
||||
return service.create(input);
|
||||
};
|
||||
```
|
||||
|
||||
### Step 4: Write Tests
|
||||
|
||||
Because the service accepts dependencies, you can test it with stubs — no running database, no framework runtime.
|
||||
|
||||
```typescript
|
||||
// _lib/server/__tests__/project.service.test.ts
|
||||
import { describe, it, expect, vi } from 'vitest';
|
||||
|
||||
import { createProjectService } from '../project.service';
|
||||
|
||||
function createMockClient(overrides: Record<string, unknown> = {}) {
|
||||
const mockChain = {
|
||||
insert: vi.fn().mockReturnThis(),
|
||||
select: vi.fn().mockReturnThis(),
|
||||
single: vi.fn().mockResolvedValue({
|
||||
data: { id: 'proj-1', name: 'Test', account_id: 'acc-1', created_at: new Date().toISOString() },
|
||||
error: null,
|
||||
}),
|
||||
delete: vi.fn().mockReturnThis(),
|
||||
eq: vi.fn().mockReturnThis(),
|
||||
order: vi.fn().mockResolvedValue({ data: [], error: null }),
|
||||
...overrides,
|
||||
};
|
||||
|
||||
return {
|
||||
from: vi.fn(() => mockChain),
|
||||
mockChain,
|
||||
} as unknown as SupabaseClient;
|
||||
}
|
||||
|
||||
describe('ProjectService', () => {
|
||||
it('creates a project', async () => {
|
||||
const client = createMockClient();
|
||||
const service = createProjectService(client);
|
||||
|
||||
const result = await service.create({
|
||||
name: 'Test Project',
|
||||
accountId: 'acc-1',
|
||||
});
|
||||
|
||||
expect(result.id).toBe('proj-1');
|
||||
expect(client.from).toHaveBeenCalledWith('projects');
|
||||
});
|
||||
|
||||
it('throws on database error', async () => {
|
||||
const client = createMockClient({
|
||||
single: vi.fn().mockResolvedValue({
|
||||
data: null,
|
||||
error: { message: 'unique violation' },
|
||||
}),
|
||||
});
|
||||
|
||||
const service = createProjectService(client);
|
||||
|
||||
await expect(
|
||||
service.create({ name: 'Dup', accountId: 'acc-1' }),
|
||||
).rejects.toEqual({ message: 'unique violation' });
|
||||
});
|
||||
});
|
||||
```
|
||||
|
||||
## Rules
|
||||
|
||||
1. **Services are pure functions over data.** Plain objects/primitives in, plain objects/primitives out. No `Request`/`Response`, no MCP context, no `FormData`.
|
||||
|
||||
2. **Inject dependencies, never import them.** The service receives its database client, storage client, or any I/O capability as a constructor argument. Never call `getSupabaseServerClient()` inside a service.
|
||||
|
||||
3. **Adapters are trivial glue.** A server action resolves the client, calls the service, and handles `revalidatePath`. An MCP tool resolves the client, calls the service, and formats the response. No business logic in adapters.
|
||||
|
||||
4. **One service, many callers.** If two interfaces do the same thing, they call the same service function. Duplicating logic is a violation.
|
||||
|
||||
5. **Testable in isolation.** Pass a mock client, assert the output. If you need a running database to test a service, refactor until you don't.
|
||||
|
||||
## What Goes Where
|
||||
|
||||
| Concern | Location | Example |
|
||||
|---------|----------|---------|
|
||||
| Input validation (Zod) | `_lib/schemas/` | `CreateProjectSchema` |
|
||||
| Business logic | `_lib/server/*.service.ts` | `ProjectService.create()` |
|
||||
| Auth check | Adapter (`enhanceAction({ auth: true })`) | Server action wrapper |
|
||||
| Logging | Adapter | `logger.info()` before/after service call |
|
||||
| Cache revalidation | Adapter | `revalidatePath()` after mutation |
|
||||
| Redirect | Adapter | `redirect()` after creation |
|
||||
| MCP response format | Adapter | Return service result as MCP content |
|
||||
|
||||
## File Structure
|
||||
|
||||
```
|
||||
feature/
|
||||
├── _lib/
|
||||
│ ├── schemas/
|
||||
│ │ └── feature.schema.ts # Zod schemas + TS types
|
||||
│ └── server/
|
||||
│ ├── feature.service.ts # Pure service (dependencies injected)
|
||||
│ ├── server-actions.ts # Server action adapters
|
||||
│ └── __tests__/
|
||||
│ └── feature.service.test.ts # Unit tests with mock client
|
||||
└── _components/
|
||||
└── feature-form.tsx
|
||||
```
|
||||
|
||||
## Anti-Patterns
|
||||
|
||||
```typescript
|
||||
// ❌ BAD: Service imports framework-specific client
|
||||
class ProjectService {
|
||||
async create(data: CreateProjectInput) {
|
||||
const client = getSupabaseServerClient(); // coupling!
|
||||
// ...
|
||||
}
|
||||
}
|
||||
|
||||
// ❌ BAD: Business logic in the adapter
|
||||
export const createProjectAction = enhanceAction(
|
||||
async function (data, user) {
|
||||
const client = getSupabaseServerClient();
|
||||
// Business logic directly in the action — not reusable
|
||||
if (data.name.length > 100) throw new Error('Name too long');
|
||||
const { data: result } = await client.from('projects').insert(data);
|
||||
return result;
|
||||
},
|
||||
{ auth: true, schema: CreateProjectSchema },
|
||||
);
|
||||
|
||||
// ❌ BAD: Two interfaces duplicate the same logic
|
||||
// server-actions.ts
|
||||
const result = await client.from('projects').insert(...).select().single();
|
||||
// mcp-tool.ts
|
||||
const result = await client.from('projects').insert(...).select().single();
|
||||
// Should be: both call projectService.create()
|
||||
```
|
||||
|
||||
## Reference
|
||||
|
||||
See `[Examples](examples.md)` for more patterns including services with multiple dependencies, services that compose other services, and testing strategies.
|
||||
Reference in New Issue
Block a user