@forgeframework/mcp-server

MCP (Model Context Protocol) server development framework for the Forge Framework.

Part of the Forge Framework — a TypeScript framework for backend microservices and web applications.

Installation

npm install @forgeframework/mcp-server

Usage

import { createMcpServerBuilder } from '@forgeframework/mcp-server';
import { z } from 'zod';

const server = createMcpServerBuilder()
  .name('forge-data-server')
  .version('1.0.0')
  .transport({ type: 'http-streaming', port: 3100, path: '/mcp' })
  .auth({
    type: 'jwt',
    jwksUrl: 'https://auth.example.com/.well-known/jwks.json',
    issuer: 'https://auth.example.com',
    audience: 'mcp-server',
  })
  .tool({
    name: 'search_documents',
    description: 'Search documents by query string',
    inputSchema: z.object({
      query: z.string().min(1).describe('Search query'),
      limit: z.number().int().min(1).max(100).default(10).describe('Max results'),
    }),
    annotations: {
      readOnlyHint: true,
      openWorldHint: false,
    },
    handler: async (input, context) => {
      const { query, limit } = input as { query: string; limit: number };
      context.progress.report({ progress: 0, total: 2, message: 'Searching...' });

      const results = await searchIndex(query, limit);
      context.progress.report({ progress: 1, total: 2, message: 'Formatting results...' });

      return {
        content: [{ type: 'text', text: JSON.stringify(results, null, 2) }],
      };
    },
  })
  .resource({
    uriTemplate: 'docs://{docId}',
    name: 'Document',
    description: 'Retrieve a document by ID',
    mimeType: 'application/json',
    handler: async (uri, context) => {
      const docId = uri.replace('docs://', '');
      const doc = await getDocument(docId);
      return {
        contents: [{ uri, text: JSON.stringify(doc), mimeType: 'application/json' }],
      };
    },
  })
  .prompt({
    name: 'summarize',
    description: 'Generate a summarization prompt for a document',
    arguments: [
      { name: 'docId', description: 'Document ID to summarize', required: true },
      { name: 'style', description: 'Summary style: brief or detailed' },
    ],
    handler: async (args, context) => {
      const doc = await getDocument(args.docId);
      const style = args.style ?? 'brief';
      return {
        messages: [
          {
            role: 'user',
            content: {
              type: 'text',
              text: `Provide a ${style} summary of the following document:\n\n${doc.content}`,
            },
          },
        ],
      };
    },
  })
  .build();

await server.start();

Documentation

Full API reference and guides: https://carbonforge.io/framework/docs/mcp/mcp-server

(Documentation site launching soon.)

License

MIT © Carbon Forge