Mcpfusion Development

f.query('tasks.filter')
    .withStrings({
        company_slug: 'Workspace identifier',
        project_slug: 'Project identifier',
    })
    .withOptionalStrings({
        title: 'Filter by title',
        workflow: 'Column name',
    })
    .withOptionalNumbers({ per_page: 'Results per page' })

// HTTP method inferred from verb: query → GET, mutation → POST, action → PUT
// Path params resolved from input: ':id' consumes input.id
// Auto-unwraps { data: ... } envelopes
f.query('user.get')
    .withString('id', 'User UUID')
    .proxy('users/:id');  // → GET users/abc-123

const createTask = f.mutation('tasks.create')
    .fromModel(TaskModel, 'create')  // imports title, description, status
    .proxy('tasks');

const updateTask = f.action('tasks.update')
    .fromModel(TaskModel, 'update')
    .handle(async (input, ctx) => {
        const data = TaskModel.toApi(input);  // alias applied, undefined stripped
        await ctx.client.put(`tasks/${input.id}`, data);
    });

f.query('docs.search')
    .describe('Search internal documentation')
    .instructions('Use ONLY when the user asks about internal policies. Do NOT use for general questions.')

const users = f.router('users')
    .describe('User management')
    .use(requireAuth)
    .tags('core');

const listUsers = users.query('list')
    .withOptionalNumber('limit', 'Max results')
    .handle(async (input, ctx) => ctx.db.users.findMany({ take: input.limit }));

const deleteUser = users.mutation('delete')
    .withString('id', 'User ID')
    .handle(async (input, ctx) => ctx.db.users.delete({ where: { id: input.id } }));

const requireAuth = f.middleware(async (ctx) => {
    const user = await db.getUser(ctx.token);
    if (!user) throw new Error('Unauthorized');
    return { user, permissions: user.permissions };
});

// ctx.user and ctx.permissions — fully typed downstream
f.mutation('admin.action')
    .use(requireAuth)
    .handle(async (input, ctx) => {
        ctx.user;        // ← typed!
        ctx.permissions; // ← typed!
    });

const project = await ctx.db.projects.findUnique({ where: { id: input.id } });
if (!project) {
    return f.error('NOT_FOUND', `Project "${input.id}" not found`)
        .suggest('Check the ID. Use projects.list to see valid IDs.')
        .actions('projects.list', 'projects.search')
        .details({ searched_id: input.id })
        .retryAfter(0);
}

f.query('geo.countries').cached();                    // immutable — cache forever
f.query('billing.balance').stale();                   // volatile — never cache
f.mutation('sprints.update').invalidates('sprints.*', 'tasks.*');  // causal invalidation

import { definePrompt, PromptMessage } from '@mcpfusion/core';

const AuditPrompt = definePrompt<AppContext>('audit', {
    args: { invoiceId: 'string' } as const,
    handler: async (ctx, { invoiceId }) => {
        const invoice = await ctx.db.getInvoice(invoiceId);
        return {
            messages: [
                PromptMessage.system('You are a Senior Financial Auditor.'),
                ...PromptMessage.fromView(InvoicePresenter.make(invoice, ctx)),
                PromptMessage.user('Begin the audit.'),
            ],
        };
    },
});

import { createMCPFusionTester } from '@mcpfusion/testing';

const tester = createMCPFusionTester(registry, {
    contextFactory: () => ({ prisma: mockPrisma, tenantId: 't_42', role: 'ADMIN' }),
});

// Egress Firewall — PII physically absent
const result = await tester.callAction('db_user', 'find_many', { take: 5 });
expect(result.data[0]).not.toHaveProperty('passwordHash');

// JIT System Rules — travel with data
expect(result.systemRules).toContain('Email addresses are PII.');

// Middleware — GUEST blocked
const denied = await tester.callAction('db_user', 'find_many', { take: 5 }, { role: 'GUEST' });
expect(denied.isError).toBe(true);

// WRONG:
const presenter = definePresenter({
    name: 'User',
    schema: z.object({ id: z.string(), name: z.string() }),  // ← NO!
});

// CORRECT:
const UserModel = defineModel('User', m => {
    m.casts({ id: m.string(), name: m.string() });
});
const presenter = definePresenter({ name: 'User', schema: UserModel });

// WRONG:
.handle(async (input, ctx) => {
    return success(await ctx.db.users.findMany());  // ← unnecessary
});

// CORRECT:
.handle(async (input, ctx) => {
    return await ctx.db.users.findMany();  // ← framework wraps automatically
});

// WRONG:
.handle(async (input, ctx) => {
    const data: Record<string, unknown> = {};
    if (input.title) data.title = input.title;
    if (input.color) data.color = input.color;
    await ctx.client.updateItem(input.id, data);
});

// CORRECT:
.handle(async (input, ctx) => {
    const data = ItemModel.toApi(input);  // strips undefined, applies aliases
    await ctx.client.updateItem(input.id, data);
});

// WRONG: model importing from tool
// models/UserModel.ts
import { listUsers } from '../agents/users.tool';  // ← NO!

// CORRECT: agents → views → models → @mcpfusion/core (one direction only)

// WRONG: formatting response manually in each handler
// CORRECT: define Presenter ONCE in views/, use .returns(Presenter) in every tool

// WRONG: defining domain fields as tool input params
f.mutation('users.create')
    .withString('name', 'User name')
    .withString('email', 'Email')        // ← These are domain fields!
    .withString('role', 'User role')

// CORRECT: use .fromModel() for domain fields
f.mutation('users.create')
    .fromModel(UserModel, 'create')      // ← imports from Model's fillable profile