@answer-engine/mcp-server 1.0.1

package/dist/__tests__/api-client.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/__tests__/api-client.test.js

@@ -0,0 +1,89 @@
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+import { AnswerEngineClient, ApiError } from '../api-client.js';
+// Mock global fetch
+const mockFetch = vi.fn();
+global.fetch = mockFetch;
+describe('AnswerEngineClient', () => {
+    let client;
+    beforeEach(() => {
+        client = new AnswerEngineClient({ apiUrl: 'http://localhost:5050', apiKey: 'ae_live_test123' });
+        mockFetch.mockReset();
+    });
+    describe('constructor', () => {
+        it('strips trailing slashes from apiUrl', async () => {
+            const c = new AnswerEngineClient({ apiUrl: 'http://example.com///', apiKey: 'key' });
+            mockFetch.mockResolvedValueOnce({
+                ok: true,
+                json: async () => ({ success: true, data: { contentTypes: {}, tags: [], capabilities: [], dateRange: { earliest: null, latest: null } }, creditsCharged: 0, creditsRemaining: 100 }),
+            });
+            await c.getSchema();
+            expect(mockFetch).toHaveBeenCalledWith('http://example.com/api/v1/agent/schema', expect.any(Object));
+        });
+    });
+    describe('request handling', () => {
+        it('sends X-API-Key header', async () => {
+            mockFetch.mockResolvedValueOnce({
+                ok: true,
+                json: async () => ({ success: true, data: { contentTypes: {}, tags: [], capabilities: [], dateRange: { earliest: null, latest: null } }, creditsCharged: 0, creditsRemaining: 100 }),
+            });
+            await client.getSchema();
+            expect(mockFetch).toHaveBeenCalledWith('http://localhost:5050/api/v1/agent/schema', expect.objectContaining({
+                headers: expect.objectContaining({ 'X-API-Key': 'ae_live_test123' }),
+            }));
+        });
+        it('throws ApiError on non-ok response', async () => {
+            mockFetch.mockResolvedValue({
+                ok: false,
+                status: 401,
+                json: async () => ({ error: { code: 'INVALID_API_KEY', message: 'Invalid key' } }),
+            });
+            await expect(client.getSchema()).rejects.toThrow(ApiError);
+            await expect(client.getSchema()).rejects.toMatchObject({
+                statusCode: 401,
+                code: 'INVALID_API_KEY',
+            });
+        });
+        it('handles missing error body gracefully', async () => {
+            mockFetch.mockResolvedValueOnce({
+                ok: false,
+                status: 500,
+                json: async () => ({}),
+            });
+            await expect(client.getSchema()).rejects.toThrow(ApiError);
+        });
+        it('sends POST body as JSON for query', async () => {
+            mockFetch.mockResolvedValueOnce({
+                ok: true,
+                json: async () => ({ success: true, data: { results: [], total: 0, searchType: 'hybrid' }, creditsCharged: 1, creditsRemaining: 99 }),
+            });
+            await client.query({ query: 'test', searchType: 'hybrid', limit: 5 });
+            const [url, options] = mockFetch.mock.calls[0];
+            expect(url).toBe('http://localhost:5050/api/v1/agent/query');
+            expect(options.method).toBe('POST');
+            expect(JSON.parse(options.body)).toEqual({ query: 'test', searchType: 'hybrid', limit: 5 });
+        });
+    });
+    describe('endpoint methods', () => {
+        const mockOkResponse = (data) => ({
+            ok: true,
+            json: async () => ({ success: true, data, creditsCharged: 1, creditsRemaining: 99 }),
+        });
+        it('getSchema calls GET /api/v1/agent/schema', async () => {
+            mockFetch.mockResolvedValueOnce(mockOkResponse({ contentTypes: {}, tags: [], capabilities: [], dateRange: { earliest: null, latest: null } }));
+            await client.getSchema();
+            expect(mockFetch.mock.calls[0][0]).toBe('http://localhost:5050/api/v1/agent/schema');
+            expect(mockFetch.mock.calls[0][1].method).toBe('GET');
+        });
+        it('scrape calls POST /api/v1/research/scrape', async () => {
+            mockFetch.mockResolvedValueOnce(mockOkResponse({ id: '1', url: 'https://example.com', title: 'Test', content: 'text' }));
+            await client.scrape('https://example.com', { includeHtml: true });
+            expect(mockFetch.mock.calls[0][0]).toBe('http://localhost:5050/api/v1/research/scrape');
+            expect(JSON.parse(mockFetch.mock.calls[0][1].body)).toEqual({ url: 'https://example.com', options: { includeHtml: true } });
+        });
+        it('webSearch calls POST /api/v1/research/search', async () => {
+            mockFetch.mockResolvedValueOnce(mockOkResponse({ results: [], query: 'test' }));
+            await client.webSearch('test', { site: 'example.com' });
+            expect(mockFetch.mock.calls[0][0]).toBe('http://localhost:5050/api/v1/research/search');
+        });
+    });
+});

package/dist/__tests__/tools.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/__tests__/tools.test.js

@@ -0,0 +1,210 @@
+import { describe, it, expect, vi } from 'vitest';
+import { handleSearchContent, handleGetContent, handleListTags } from '../tools.js';
+import { ApiError } from '../api-client.js';
+// Create a mock client
+function createMockClient(overrides = {}) {
+    return {
+        getSchema: vi.fn(),
+        query: vi.fn(),
+        retrieve: vi.fn(),
+        summarize: vi.fn(),
+        scrape: vi.fn(),
+        crawl: vi.fn(),
+        webSearch: vi.fn(),
+        ...overrides,
+    };
+}
+describe('MCP Tool Handlers', () => {
+    describe('handleSearchContent', () => {
+        it('returns formatted results', async () => {
+            const client = createMockClient({
+                query: vi.fn().mockResolvedValue({
+                    data: {
+                        results: [
+                            {
+                                id: '1',
+                                title: 'Test',
+                                contentType: 'page',
+                                relevanceScore: 0.95,
+                                tags: [{ label: 'Tag1', slug: 'tag1', category: null }],
+                                summary: null,
+                                createdAt: '2024-01-01',
+                            },
+                        ],
+                        total: 1,
+                        searchType: 'hybrid',
+                    },
+                    creditsCharged: 1,
+                    creditsRemaining: 99,
+                }),
+            });
+            const result = await handleSearchContent(client, {
+                query: 'test',
+                searchType: 'hybrid',
+                limit: 10,
+                include: ['summary', 'tags'],
+            });
+            expect(result).toContain('Search Results');
+            expect(result).toContain('Test');
+            expect(result).toContain('0.950');
+            expect(result).toContain('Credits charged: 1');
+        });
+        it('returns no results message', async () => {
+            const client = createMockClient({
+                query: vi.fn().mockResolvedValue({
+                    data: { results: [], total: 0, searchType: 'hybrid' },
+                    creditsCharged: 1,
+                    creditsRemaining: 99,
+                }),
+            });
+            const result = await handleSearchContent(client, {
+                query: 'nothing',
+                searchType: 'hybrid',
+                limit: 10,
+                include: ['summary'],
+            });
+            expect(result).toContain('No results found');
+        });
+        it('propagates ApiError', async () => {
+            const client = createMockClient({
+                query: vi.fn().mockRejectedValue(new ApiError(401, 'INVALID_API_KEY', 'Bad key')),
+            });
+            await expect(handleSearchContent(client, { query: 'test', searchType: 'hybrid', limit: 10, include: [] })).rejects.toThrow(ApiError);
+        });
+        it('includes tags in output when present', async () => {
+            const client = createMockClient({
+                query: vi.fn().mockResolvedValue({
+                    data: {
+                        results: [
+                            {
+                                id: '2',
+                                title: 'Tagged Article',
+                                contentType: 'article',
+                                relevanceScore: 0.8,
+                                tags: [
+                                    { label: 'Engineering', slug: 'engineering', category: 'dept' },
+                                    { label: 'Backend', slug: 'backend', category: 'dept' },
+                                ],
+                                summary: 'A great article',
+                                createdAt: '2024-06-01',
+                            },
+                        ],
+                        total: 1,
+                        searchType: 'fulltext',
+                    },
+                    creditsCharged: 1,
+                    creditsRemaining: 50,
+                }),
+            });
+            const result = await handleSearchContent(client, {
+                query: 'engineering',
+                searchType: 'fulltext',
+                limit: 5,
+                include: ['summary', 'tags'],
+            });
+            expect(result).toContain('Engineering');
+            expect(result).toContain('Backend');
+            expect(result).toContain('A great article');
+        });
+    });
+    describe('handleGetContent', () => {
+        it('returns formatted items', async () => {
+            const client = createMockClient({
+                retrieve: vi.fn().mockResolvedValue({
+                    data: {
+                        items: [
+                            {
+                                id: 'abc-123',
+                                title: 'My Page',
+                                contentType: 'page',
+                                createdAt: '2024-01-01',
+                                updatedAt: '2024-01-02',
+                                sourceUrl: 'https://example.com/page',
+                                summary: 'A summary',
+                                tags: [],
+                                content: 'Full content here',
+                                children: [],
+                            },
+                        ],
+                    },
+                    creditsCharged: 1,
+                    creditsRemaining: 98,
+                }),
+            });
+            const result = await handleGetContent(client, { ids: ['abc-123'], include: ['content', 'summary'] });
+            expect(result).toContain('My Page');
+            expect(result).toContain('https://example.com/page');
+            expect(result).toContain('Full content here');
+            expect(result).toContain('Credits charged: 1');
+        });
+        it('returns no items message when empty', async () => {
+            const client = createMockClient({
+                retrieve: vi.fn().mockResolvedValue({
+                    data: { items: [] },
+                    creditsCharged: 1,
+                    creditsRemaining: 97,
+                }),
+            });
+            const result = await handleGetContent(client, { ids: ['missing-id'], include: ['summary'] });
+            expect(result).toContain('No items found');
+        });
+        it('propagates ApiError', async () => {
+            const client = createMockClient({
+                retrieve: vi.fn().mockRejectedValue(new ApiError(402, 'INSUFFICIENT_CREDITS', 'No credits')),
+            });
+            await expect(handleGetContent(client, { ids: ['id-1'], include: ['content'] })).rejects.toThrow(ApiError);
+        });
+    });
+    describe('handleListTags', () => {
+        it('groups tags by category', async () => {
+            const client = createMockClient({
+                getSchema: vi.fn().mockResolvedValue({
+                    data: {
+                        contentTypes: { page: 5, article: 3 },
+                        tags: [
+                            { slug: 'a', label: 'A', category: 'cat1', description: 'desc' },
+                            { slug: 'b', label: 'B', category: 'cat1', description: null },
+                            { slug: 'c', label: 'C', category: null, description: null },
+                        ],
+                        capabilities: ['search', 'retrieve'],
+                        dateRange: { earliest: '2024-01-01', latest: '2024-12-31' },
+                    },
+                    creditsCharged: 0,
+                    creditsRemaining: 100,
+                }),
+            });
+            const result = await handleListTags(client);
+            expect(result).toContain('cat1');
+            expect(result).toContain('uncategorized');
+            expect(result).toContain('page');
+            expect(result).toContain('article');
+            expect(result).toContain('search, retrieve');
+            expect(result).toContain('2024-01-01');
+        });
+        it('includes tag descriptions when present', async () => {
+            const client = createMockClient({
+                getSchema: vi.fn().mockResolvedValue({
+                    data: {
+                        contentTypes: {},
+                        tags: [
+                            { slug: 'tech', label: 'Technology', category: 'topic', description: 'Tech articles' },
+                        ],
+                        capabilities: [],
+                        dateRange: { earliest: null, latest: null },
+                    },
+                    creditsCharged: 0,
+                    creditsRemaining: 100,
+                }),
+            });
+            const result = await handleListTags(client);
+            expect(result).toContain('Tech articles');
+            expect(result).toContain('Technology');
+        });
+        it('propagates ApiError', async () => {
+            const client = createMockClient({
+                getSchema: vi.fn().mockRejectedValue(new ApiError(429, 'RATE_LIMIT', 'Too many requests')),
+            });
+            await expect(handleListTags(client)).rejects.toThrow(ApiError);
+        });
+    });
+});

package/dist/api-client.d.ts

@@ -0,0 +1,153 @@
+/**
+ * Answer Engine API Client
+ * HTTP wrapper for agent query and research endpoints
+ */
+interface ApiResponse<T> {
+    success: boolean;
+    data: T;
+    creditsCharged: number;
+    creditsRemaining: number;
+}
+export interface ApiClientConfig {
+    apiUrl: string;
+    apiKey: string;
+}
+export declare class AnswerEngineClient {
+    private apiUrl;
+    private apiKey;
+    constructor(config: ApiClientConfig);
+    private request;
+    getSchema(): Promise<ApiResponse<SchemaResponse>>;
+    query(input: QueryInput): Promise<ApiResponse<QueryResult>>;
+    retrieve(input: RetrieveInput): Promise<ApiResponse<RetrieveResult>>;
+    summarize(input: SummarizeInput): Promise<ApiResponse<SummarizeResult>>;
+    scrape(url: string, options?: {
+        includeHtml?: boolean;
+    }): Promise<ApiResponse<ScrapeResult>>;
+    crawl(domain: string, maxPages?: number): Promise<ApiResponse<CrawlResult>>;
+    webSearch(query: string, options?: {
+        site?: string;
+        scrapeResults?: boolean;
+    }): Promise<ApiResponse<WebSearchResult>>;
+}
+export declare class ApiError extends Error {
+    readonly statusCode: number;
+    readonly code: string;
+    constructor(statusCode: number, code: string, message: string);
+}
+export interface SchemaResponse {
+    contentTypes: Record<string, number>;
+    tags: Array<{
+        slug: string;
+        label: string;
+        description: string | null;
+        category: string | null;
+    }>;
+    capabilities: string[];
+    dateRange: {
+        earliest: string | null;
+        latest: string | null;
+    };
+}
+export interface QueryInput {
+    query: string;
+    searchType?: 'fulltext' | 'semantic' | 'hybrid';
+    filters?: {
+        contentTypes?: string[];
+        tags?: string[];
+        dateFrom?: string;
+        dateTo?: string;
+        status?: 'active' | 'archived';
+    };
+    include?: Array<'summary' | 'content' | 'tags' | 'metadata'>;
+    limit?: number;
+}
+export interface QueryResultItem {
+    id: string;
+    contentType: string;
+    title: string;
+    summary?: string | null;
+    content?: string | null;
+    tags?: Array<{
+        slug: string;
+        label: string;
+        category: string | null;
+    }>;
+    metadata?: Record<string, unknown>;
+    relevanceScore: number;
+    createdAt: string;
+}
+export interface QueryResult {
+    results: QueryResultItem[];
+    total: number;
+    searchType: string;
+}
+export interface RetrieveInput {
+    ids: string[];
+    include?: Array<'summary' | 'content' | 'tags' | 'metadata' | 'children' | 'analysis'>;
+}
+export interface RetrieveResultItem {
+    id: string;
+    contentType: string;
+    title: string;
+    summary?: string | null;
+    content?: string | null;
+    tags?: Array<{
+        slug: string;
+        label: string;
+        category: string | null;
+    }>;
+    metadata?: Record<string, unknown>;
+    analysis?: Record<string, unknown>;
+    children?: Array<{
+        id: string;
+        title: string;
+        contentType: string;
+    }>;
+    sourceUrl: string | null;
+    createdAt: string;
+    updatedAt: string;
+}
+export interface RetrieveResult {
+    items: RetrieveResultItem[];
+}
+export interface SummarizeInput {
+    prompt: string;
+    filter?: {
+        contentTypes?: string[];
+        tags?: string[];
+        dateFrom?: string;
+        dateTo?: string;
+    };
+    limit?: number;
+}
+export interface SummarizeResult {
+    summary: string;
+    sourceCount: number;
+    prompt: string;
+}
+export interface ScrapeResult {
+    id: string;
+    url: string;
+    title: string;
+    content: string;
+    html?: string;
+}
+export interface CrawlResult {
+    pages: Array<{
+        url: string;
+        title: string;
+        status: string;
+    }>;
+    totalPages: number;
+}
+export interface WebSearchResult {
+    results: Array<{
+        title: string;
+        url: string;
+        snippet: string;
+        content?: string;
+    }>;
+    query: string;
+}
+export {};

package/dist/api-client.js

@@ -0,0 +1,63 @@
+/**
+ * Answer Engine API Client
+ * HTTP wrapper for agent query and research endpoints
+ */
+export class AnswerEngineClient {
+    apiUrl;
+    apiKey;
+    constructor(config) {
+        this.apiUrl = config.apiUrl.replace(/\/+$/, '');
+        this.apiKey = config.apiKey;
+    }
+    async request(method, path, body) {
+        const headers = {
+            'Content-Type': 'application/json',
+            'X-API-Key': this.apiKey,
+        };
+        const options = { method, headers };
+        if (body)
+            options.body = JSON.stringify(body);
+        const response = await fetch(`${this.apiUrl}${path}`, options);
+        const data = (await response.json());
+        if (!response.ok) {
+            const errorData = data;
+            const code = errorData.error?.code ?? `HTTP_${response.status}`;
+            const message = errorData.error?.message ?? `Request failed with status ${response.status}`;
+            throw new ApiError(response.status, code, message);
+        }
+        return data;
+    }
+    // Agent endpoints
+    async getSchema() {
+        return this.request('GET', '/api/v1/agent/schema');
+    }
+    async query(input) {
+        return this.request('POST', '/api/v1/agent/query', input);
+    }
+    async retrieve(input) {
+        return this.request('POST', '/api/v1/agent/retrieve', input);
+    }
+    async summarize(input) {
+        return this.request('POST', '/api/v1/agent/summarize', input);
+    }
+    // Research endpoints
+    async scrape(url, options) {
+        return this.request('POST', '/api/v1/research/scrape', { url, options });
+    }
+    async crawl(domain, maxPages) {
+        return this.request('POST', '/api/v1/research/crawl', { domain, maxPages });
+    }
+    async webSearch(query, options) {
+        return this.request('POST', '/api/v1/research/search', { query, options });
+    }
+}
+export class ApiError extends Error {
+    statusCode;
+    code;
+    constructor(statusCode, code, message) {
+        super(message);
+        this.statusCode = statusCode;
+        this.code = code;
+        this.name = 'ApiError';
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1,6 @@
+#!/usr/bin/env node
+/**
+ * Answer Engine MCP Server
+ * Provides Answer Engine search, retrieval, and research capabilities via MCP stdio transport
+ */
+export {};

package/dist/index.js

@@ -0,0 +1,135 @@
+#!/usr/bin/env node
+/**
+ * Answer Engine MCP Server
+ * Provides Answer Engine search, retrieval, and research capabilities via MCP stdio transport
+ */
+import { McpServer, ResourceTemplate } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { z } from 'zod';
+import { AnswerEngineClient, ApiError } from './api-client.js';
+import { SearchContentSchema, GetContentSchema, SummarizeCollectionSchema, ScrapeUrlSchema, CrawlDomainSchema, WebSearchSchema, handleSearchContent, handleGetContent, handleListTags, handleSummarizeCollection, handleScrapeUrl, handleCrawlDomain, handleWebSearch, } from './tools.js';
+import { staticResources, resourceTemplateConfigs, readResource } from './resources.js';
+// Configuration from environment
+const API_URL = process.env.ANSWER_ENGINE_API_URL ?? 'http://localhost:5050';
+const API_KEY = process.env.ANSWER_ENGINE_API_KEY ?? '';
+if (!API_KEY) {
+    process.stderr.write('Warning: ANSWER_ENGINE_API_KEY not set. API calls will fail.\n');
+}
+// Create API client
+const client = new AnswerEngineClient({ apiUrl: API_URL, apiKey: API_KEY });
+// Format errors for MCP error responses
+function formatMcpError(error) {
+    if (error instanceof ApiError) {
+        if (error.statusCode === 401)
+            return 'Authentication failed. Check your ANSWER_ENGINE_API_KEY.';
+        if (error.statusCode === 402)
+            return 'Insufficient credits. Please add more credits to your account.';
+        if (error.statusCode === 429)
+            return 'Rate limit exceeded. Please wait before making more requests.';
+        return `API error (${error.code}): ${error.message}`;
+    }
+    if (error instanceof z.ZodError) {
+        return `Invalid input: ${error.errors.map(e => `${e.path.join('.')}: ${e.message}`).join(', ')}`;
+    }
+    return `Unexpected error: ${String(error)}`;
+}
+// Create MCP server
+const server = new McpServer({
+    name: 'answer-engine',
+    version: '1.0.0',
+});
+// -----------------------------------------------------------------------
+// Register tools — pass .shape (ZodRawShape), not the ZodObject itself
+// -----------------------------------------------------------------------
+server.tool('search_content', 'Search your Answer Engine content library using fulltext, semantic, or hybrid search. Returns matching content items with relevance scores. Costs 1 credit per search.', SearchContentSchema.shape, async (params) => {
+    try {
+        const text = await handleSearchContent(client, params);
+        return { content: [{ type: 'text', text }] };
+    }
+    catch (error) {
+        return { content: [{ type: 'text', text: formatMcpError(error) }], isError: true };
+    }
+});
+server.tool('get_content', 'Retrieve specific content items by their IDs. Returns full content details including text, tags, metadata, and children. Costs 1 credit.', GetContentSchema.shape, async (params) => {
+    try {
+        const text = await handleGetContent(client, params);
+        return { content: [{ type: 'text', text }] };
+    }
+    catch (error) {
+        return { content: [{ type: 'text', text: formatMcpError(error) }], isError: true };
+    }
+});
+server.tool('list_tags', 'List all available tags and content types in your Answer Engine library. Useful for discovering what content is available and filtering searches. Free (0 credits).', {}, async () => {
+    try {
+        const text = await handleListTags(client);
+        return { content: [{ type: 'text', text }] };
+    }
+    catch (error) {
+        return { content: [{ type: 'text', text: formatMcpError(error) }], isError: true };
+    }
+});
+server.tool('summarize_collection', 'Use AI to summarize or analyze content from your Answer Engine library. Provide a prompt describing what you want to know, and optionally filter by content type, tags, or dates. Costs 10 credits.', SummarizeCollectionSchema.shape, async (params) => {
+    try {
+        const text = await handleSummarizeCollection(client, params);
+        return { content: [{ type: 'text', text }] };
+    }
+    catch (error) {
+        return { content: [{ type: 'text', text: formatMcpError(error) }], isError: true };
+    }
+});
+server.tool('scrape_url', 'Scrape a web page and save it to your Answer Engine content library. Returns the extracted title and content. Costs 1 credit.', ScrapeUrlSchema.shape, async (params) => {
+    try {
+        const text = await handleScrapeUrl(client, params);
+        return { content: [{ type: 'text', text }] };
+    }
+    catch (error) {
+        return { content: [{ type: 'text', text: formatMcpError(error) }], isError: true };
+    }
+});
+server.tool('crawl_domain', 'Crawl multiple pages from a domain and save them to your Answer Engine library. Costs 1 credit per page crawled.', CrawlDomainSchema.shape, async (params) => {
+    try {
+        const text = await handleCrawlDomain(client, params);
+        return { content: [{ type: 'text', text }] };
+    }
+    catch (error) {
+        return { content: [{ type: 'text', text: formatMcpError(error) }], isError: true };
+    }
+});
+server.tool('web_search', 'Search the web and optionally scrape results. Use the site parameter to limit to a specific domain. Costs 1 credit.', WebSearchSchema.shape, async (params) => {
+    try {
+        const text = await handleWebSearch(client, params);
+        return { content: [{ type: 'text', text }] };
+    }
+    catch (error) {
+        return { content: [{ type: 'text', text: formatMcpError(error) }], isError: true };
+    }
+});
+// -----------------------------------------------------------------------
+// Register static resources
+// -----------------------------------------------------------------------
+for (const resource of staticResources) {
+    server.resource(resource.name, resource.uri, { description: resource.description, mimeType: resource.mimeType }, async (uri) => {
+        return readResource(client, uri.href);
+    });
+}
+// -----------------------------------------------------------------------
+// Register resource templates
+// -----------------------------------------------------------------------
+for (const templateConfig of resourceTemplateConfigs) {
+    const template = new ResourceTemplate(templateConfig.uriTemplate, { list: undefined });
+    server.resource(templateConfig.name, template, { description: templateConfig.description, mimeType: templateConfig.mimeType }, async (uri) => {
+        return readResource(client, uri.href);
+    });
+}
+// -----------------------------------------------------------------------
+// Start server
+// -----------------------------------------------------------------------
+async function main() {
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    process.stderr.write('Answer Engine MCP server started\n');
+}
+main().catch((error) => {
+    process.stderr.write(`Fatal error: ${String(error)}\n`);
+    process.exit(1);
+});

package/dist/resources.d.ts

@@ -0,0 +1,25 @@
+/**
+ * MCP Resource Definitions
+ * Expose Answer Engine data as MCP resources
+ */
+import { AnswerEngineClient } from './api-client.js';
+export interface ResourceMetadata {
+    uri: string;
+    name: string;
+    description: string;
+    mimeType: string;
+}
+export declare const staticResources: ResourceMetadata[];
+export declare const resourceTemplateConfigs: {
+    uriTemplate: string;
+    name: string;
+    description: string;
+    mimeType: string;
+}[];
+export declare function readResource(client: AnswerEngineClient, uri: string): Promise<{
+    contents: Array<{
+        uri: string;
+        mimeType: string;
+        text: string;
+    }>;
+}>;

package/dist/resources.js

@@ -0,0 +1,65 @@
+/**
+ * MCP Resource Definitions
+ * Expose Answer Engine data as MCP resources
+ */
+import { ApiError } from './api-client.js';
+export const staticResources = [
+    {
+        uri: 'answer-engine://schema',
+        name: 'Content Schema',
+        description: 'Available content types, tags, and capabilities in your Answer Engine library',
+        mimeType: 'application/json',
+    },
+];
+export const resourceTemplateConfigs = [
+    {
+        uriTemplate: 'answer-engine://content/{id}',
+        name: 'Content Item',
+        description: 'Retrieve a specific content item by ID',
+        mimeType: 'application/json',
+    },
+];
+export async function readResource(client, uri) {
+    try {
+        if (uri === 'answer-engine://schema') {
+            const response = await client.getSchema();
+            return {
+                contents: [
+                    {
+                        uri,
+                        mimeType: 'application/json',
+                        text: JSON.stringify(response.data, null, 2),
+                    },
+                ],
+            };
+        }
+        const contentMatch = /^answer-engine:\/\/content\/(.+)$/.exec(uri);
+        if (contentMatch) {
+            const id = contentMatch[1];
+            const response = await client.retrieve({
+                ids: [id],
+                include: ['summary', 'content', 'tags', 'metadata', 'children'],
+            });
+            const item = response.data.items[0];
+            if (!item) {
+                throw new Error(`Content item not found: ${id}`);
+            }
+            return {
+                contents: [
+                    {
+                        uri,
+                        mimeType: 'application/json',
+                        text: JSON.stringify(item, null, 2),
+                    },
+                ],
+            };
+        }
+        throw new Error(`Unknown resource URI: ${uri}`);
+    }
+    catch (error) {
+        if (error instanceof ApiError) {
+            throw new Error(`API error (${error.code}): ${error.message}`);
+        }
+        throw error;
+    }
+}

package/dist/tools.d.ts

@@ -0,0 +1,138 @@
+/**
+ * MCP Tool Definitions
+ * Maps Answer Engine API endpoints to MCP tools with Zod input schemas
+ */
+import { z } from 'zod';
+import { AnswerEngineClient } from './api-client.js';
+export declare const SearchContentSchema: z.ZodObject<{
+    query: z.ZodString;
+    searchType: z.ZodDefault<z.ZodEnum<["fulltext", "semantic", "hybrid"]>>;
+    filters: z.ZodOptional<z.ZodObject<{
+        contentTypes: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+        tags: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+        dateFrom: z.ZodOptional<z.ZodString>;
+        dateTo: z.ZodOptional<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        tags?: string[] | undefined;
+        contentTypes?: string[] | undefined;
+        dateFrom?: string | undefined;
+        dateTo?: string | undefined;
+    }, {
+        tags?: string[] | undefined;
+        contentTypes?: string[] | undefined;
+        dateFrom?: string | undefined;
+        dateTo?: string | undefined;
+    }>>;
+    limit: z.ZodDefault<z.ZodNumber>;
+    include: z.ZodDefault<z.ZodArray<z.ZodEnum<["summary", "content", "tags", "metadata"]>, "many">>;
+}, "strip", z.ZodTypeAny, {
+    query: string;
+    searchType: "fulltext" | "semantic" | "hybrid";
+    limit: number;
+    include: ("summary" | "content" | "tags" | "metadata")[];
+    filters?: {
+        tags?: string[] | undefined;
+        contentTypes?: string[] | undefined;
+        dateFrom?: string | undefined;
+        dateTo?: string | undefined;
+    } | undefined;
+}, {
+    query: string;
+    searchType?: "fulltext" | "semantic" | "hybrid" | undefined;
+    filters?: {
+        tags?: string[] | undefined;
+        contentTypes?: string[] | undefined;
+        dateFrom?: string | undefined;
+        dateTo?: string | undefined;
+    } | undefined;
+    limit?: number | undefined;
+    include?: ("summary" | "content" | "tags" | "metadata")[] | undefined;
+}>;
+export declare const GetContentSchema: z.ZodObject<{
+    ids: z.ZodArray<z.ZodString, "many">;
+    include: z.ZodDefault<z.ZodArray<z.ZodEnum<["summary", "content", "tags", "metadata", "children", "analysis"]>, "many">>;
+}, "strip", z.ZodTypeAny, {
+    include: ("summary" | "content" | "tags" | "metadata" | "children" | "analysis")[];
+    ids: string[];
+}, {
+    ids: string[];
+    include?: ("summary" | "content" | "tags" | "metadata" | "children" | "analysis")[] | undefined;
+}>;
+export declare const SummarizeCollectionSchema: z.ZodObject<{
+    prompt: z.ZodString;
+    filter: z.ZodOptional<z.ZodObject<{
+        contentTypes: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+        tags: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+        dateFrom: z.ZodOptional<z.ZodString>;
+        dateTo: z.ZodOptional<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        tags?: string[] | undefined;
+        contentTypes?: string[] | undefined;
+        dateFrom?: string | undefined;
+        dateTo?: string | undefined;
+    }, {
+        tags?: string[] | undefined;
+        contentTypes?: string[] | undefined;
+        dateFrom?: string | undefined;
+        dateTo?: string | undefined;
+    }>>;
+    limit: z.ZodDefault<z.ZodNumber>;
+}, "strip", z.ZodTypeAny, {
+    limit: number;
+    prompt: string;
+    filter?: {
+        tags?: string[] | undefined;
+        contentTypes?: string[] | undefined;
+        dateFrom?: string | undefined;
+        dateTo?: string | undefined;
+    } | undefined;
+}, {
+    prompt: string;
+    filter?: {
+        tags?: string[] | undefined;
+        contentTypes?: string[] | undefined;
+        dateFrom?: string | undefined;
+        dateTo?: string | undefined;
+    } | undefined;
+    limit?: number | undefined;
+}>;
+export declare const ScrapeUrlSchema: z.ZodObject<{
+    url: z.ZodString;
+    includeHtml: z.ZodDefault<z.ZodBoolean>;
+}, "strip", z.ZodTypeAny, {
+    url: string;
+    includeHtml: boolean;
+}, {
+    url: string;
+    includeHtml?: boolean | undefined;
+}>;
+export declare const CrawlDomainSchema: z.ZodObject<{
+    domain: z.ZodString;
+    maxPages: z.ZodDefault<z.ZodNumber>;
+}, "strip", z.ZodTypeAny, {
+    domain: string;
+    maxPages: number;
+}, {
+    domain: string;
+    maxPages?: number | undefined;
+}>;
+export declare const WebSearchSchema: z.ZodObject<{
+    query: z.ZodString;
+    site: z.ZodOptional<z.ZodString>;
+    scrapeResults: z.ZodDefault<z.ZodBoolean>;
+}, "strip", z.ZodTypeAny, {
+    query: string;
+    scrapeResults: boolean;
+    site?: string | undefined;
+}, {
+    query: string;
+    site?: string | undefined;
+    scrapeResults?: boolean | undefined;
+}>;
+export declare function handleSearchContent(client: AnswerEngineClient, input: z.infer<typeof SearchContentSchema>): Promise<string>;
+export declare function handleGetContent(client: AnswerEngineClient, input: z.infer<typeof GetContentSchema>): Promise<string>;
+export declare function handleListTags(client: AnswerEngineClient): Promise<string>;
+export declare function handleSummarizeCollection(client: AnswerEngineClient, input: z.infer<typeof SummarizeCollectionSchema>): Promise<string>;
+export declare function handleScrapeUrl(client: AnswerEngineClient, input: z.infer<typeof ScrapeUrlSchema>): Promise<string>;
+export declare function handleCrawlDomain(client: AnswerEngineClient, input: z.infer<typeof CrawlDomainSchema>): Promise<string>;
+export declare function handleWebSearch(client: AnswerEngineClient, input: z.infer<typeof WebSearchSchema>): Promise<string>;

package/dist/tools.js

@@ -0,0 +1,223 @@
+/**
+ * MCP Tool Definitions
+ * Maps Answer Engine API endpoints to MCP tools with Zod input schemas
+ */
+import { z } from 'zod';
+// -----------------------------------------------------------------------
+// Input schemas (ZodObject so we can expose .shape to the MCP SDK)
+// -----------------------------------------------------------------------
+export const SearchContentSchema = z.object({
+    query: z.string().describe('Search query text'),
+    searchType: z
+        .enum(['fulltext', 'semantic', 'hybrid'])
+        .default('hybrid')
+        .describe('Search algorithm to use'),
+    filters: z
+        .object({
+        contentTypes: z.array(z.string()).optional().describe('Filter by content types'),
+        tags: z.array(z.string()).optional().describe('Filter by tag slugs'),
+        dateFrom: z.string().optional().describe('Filter: created after this ISO date'),
+        dateTo: z.string().optional().describe('Filter: created before this ISO date'),
+    })
+        .optional()
+        .describe('Optional filters to narrow results'),
+    limit: z
+        .number()
+        .int()
+        .min(1)
+        .max(50)
+        .default(10)
+        .describe('Maximum number of results'),
+    include: z
+        .array(z.enum(['summary', 'content', 'tags', 'metadata']))
+        .default(['summary', 'tags'])
+        .describe('Fields to include in results'),
+});
+export const GetContentSchema = z.object({
+    ids: z.array(z.string()).min(1).max(50).describe('Content item UUIDs to retrieve'),
+    include: z
+        .array(z.enum(['summary', 'content', 'tags', 'metadata', 'children', 'analysis']))
+        .default(['summary', 'content', 'tags'])
+        .describe('Fields to include'),
+});
+export const SummarizeCollectionSchema = z.object({
+    prompt: z.string().describe('What to summarize or analyze about the content'),
+    filter: z
+        .object({
+        contentTypes: z.array(z.string()).optional(),
+        tags: z.array(z.string()).optional(),
+        dateFrom: z.string().optional(),
+        dateTo: z.string().optional(),
+    })
+        .optional()
+        .describe('Filter which content to include in the summary'),
+    limit: z
+        .number()
+        .int()
+        .min(1)
+        .max(100)
+        .default(20)
+        .describe('Max content items to analyze'),
+});
+export const ScrapeUrlSchema = z.object({
+    url: z.string().url().describe('URL to scrape'),
+    includeHtml: z.boolean().default(false).describe('Include raw HTML in response'),
+});
+export const CrawlDomainSchema = z.object({
+    domain: z.string().describe('Domain to crawl (e.g., example.com)'),
+    maxPages: z
+        .number()
+        .int()
+        .min(1)
+        .max(100)
+        .default(10)
+        .describe('Maximum pages to crawl (1 credit per page)'),
+});
+export const WebSearchSchema = z.object({
+    query: z.string().describe('Search query'),
+    site: z.string().optional().describe('Limit search to a specific site'),
+    scrapeResults: z
+        .boolean()
+        .default(false)
+        .describe('Scrape full content from search result URLs'),
+});
+// -----------------------------------------------------------------------
+// Helpers
+// -----------------------------------------------------------------------
+function formatCredits(creditsCharged, creditsRemaining) {
+    return `\n\n---\nCredits charged: ${creditsCharged} | Credits remaining: ${creditsRemaining}`;
+}
+// -----------------------------------------------------------------------
+// Tool handlers
+// -----------------------------------------------------------------------
+export async function handleSearchContent(client, input) {
+    const response = await client.query(input);
+    const { results, total, searchType } = response.data;
+    if (results.length === 0) {
+        return `No results found for "${input.query}" (${searchType} search).${formatCredits(response.creditsCharged, response.creditsRemaining)}`;
+    }
+    let output = `## Search Results (${total} total, showing ${results.length}, ${searchType})\n\n`;
+    for (const item of results) {
+        output += `### ${item.title}\n`;
+        output += `- **ID:** ${item.id}\n`;
+        output += `- **Type:** ${item.contentType}\n`;
+        output += `- **Relevance:** ${item.relevanceScore.toFixed(3)}\n`;
+        if (item.summary)
+            output += `- **Summary:** ${item.summary}\n`;
+        if (item.tags?.length)
+            output += `- **Tags:** ${item.tags.map((t) => t.label).join(', ')}\n`;
+        output += '\n';
+    }
+    output += formatCredits(response.creditsCharged, response.creditsRemaining);
+    return output;
+}
+export async function handleGetContent(client, input) {
+    const response = await client.retrieve(input);
+    const { items } = response.data;
+    if (items.length === 0) {
+        return `No items found for the provided IDs.${formatCredits(response.creditsCharged, response.creditsRemaining)}`;
+    }
+    let output = `## Retrieved ${items.length} Item(s)\n\n`;
+    for (const item of items) {
+        output += `### ${item.title}\n`;
+        output += `- **ID:** ${item.id}\n`;
+        output += `- **Type:** ${item.contentType}\n`;
+        output += `- **Created:** ${item.createdAt}\n`;
+        if (item.sourceUrl)
+            output += `- **URL:** ${item.sourceUrl}\n`;
+        if (item.summary)
+            output += `- **Summary:** ${item.summary}\n`;
+        if (item.tags?.length)
+            output += `- **Tags:** ${item.tags.map((t) => t.label).join(', ')}\n`;
+        if (item.content)
+            output += `\n${item.content}\n`;
+        if (item.children?.length) {
+            output += `\n**Children (${item.children.length}):**\n`;
+            for (const child of item.children) {
+                output += `  - ${child.title} (${child.id})\n`;
+            }
+        }
+        output += '\n';
+    }
+    output += formatCredits(response.creditsCharged, response.creditsRemaining);
+    return output;
+}
+export async function handleListTags(client) {
+    const response = await client.getSchema();
+    const { contentTypes, tags, capabilities, dateRange } = response.data;
+    let output = '## Content Schema\n\n';
+    output += '### Content Types\n';
+    for (const [type, count] of Object.entries(contentTypes)) {
+        output += `- **${type}:** ${count} items\n`;
+    }
+    output += `\n### Tags (${tags.length} total)\n`;
+    const byCategory = {};
+    for (const tag of tags) {
+        const cat = tag.category ?? 'uncategorized';
+        if (!byCategory[cat])
+            byCategory[cat] = [];
+        byCategory[cat].push(tag);
+    }
+    for (const [category, categoryTags] of Object.entries(byCategory)) {
+        output += `\n**${category}:**\n`;
+        for (const tag of categoryTags) {
+            output += `- ${tag.label} (\`${tag.slug}\`)`;
+            if (tag.description)
+                output += ` — ${tag.description}`;
+            output += '\n';
+        }
+    }
+    output += `\n### Capabilities\n${capabilities.join(', ')}\n`;
+    output += `\n### Date Range\n${dateRange.earliest ?? 'n/a'} -> ${dateRange.latest ?? 'n/a'}\n`;
+    output += formatCredits(response.creditsCharged, response.creditsRemaining);
+    return output;
+}
+export async function handleSummarizeCollection(client, input) {
+    const response = await client.summarize(input);
+    const { summary, sourceCount } = response.data;
+    let output = `## Summary (${sourceCount} sources analyzed)\n\n`;
+    output += summary;
+    output += formatCredits(response.creditsCharged, response.creditsRemaining);
+    return output;
+}
+export async function handleScrapeUrl(client, input) {
+    const response = await client.scrape(input.url, { includeHtml: input.includeHtml });
+    const { title, url, content } = response.data;
+    let output = `## Scraped: ${title}\n`;
+    output += `**URL:** ${url}\n\n`;
+    output += content;
+    output += formatCredits(response.creditsCharged, response.creditsRemaining);
+    return output;
+}
+export async function handleCrawlDomain(client, input) {
+    const response = await client.crawl(input.domain, input.maxPages);
+    const { pages, totalPages } = response.data;
+    let output = `## Crawl Results: ${input.domain} (${totalPages} pages)\n\n`;
+    for (const page of pages) {
+        const icon = page.status === 'success' ? '+' : 'x';
+        output += `${icon} ${page.title} -- ${page.url}\n`;
+    }
+    output += formatCredits(response.creditsCharged, response.creditsRemaining);
+    return output;
+}
+export async function handleWebSearch(client, input) {
+    const response = await client.webSearch(input.query, {
+        site: input.site,
+        scrapeResults: input.scrapeResults,
+    });
+    const { results, query: searchQuery } = response.data;
+    if (results.length === 0) {
+        return `No web results found for "${searchQuery}".${formatCredits(response.creditsCharged, response.creditsRemaining)}`;
+    }
+    let output = `## Web Search: "${searchQuery}" (${results.length} results)\n\n`;
+    for (const result of results) {
+        output += `### ${result.title}\n`;
+        output += `**URL:** ${result.url}\n`;
+        output += `${result.snippet}\n`;
+        if (result.content)
+            output += `\n${result.content}\n`;
+        output += '\n';
+    }
+    output += formatCredits(response.creditsCharged, response.creditsRemaining);
+    return output;
+}

package/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "@answer-engine/mcp-server",
+  "version": "1.0.1",
+  "description": "MCP server for Answer Engine - search, retrieve, and research content",
+  "type": "module",
+  "main": "dist/index.js",
+  "bin": {
+    "answer-engine-mcp": "dist/index.js"
+  },
+  "files": [
+    "dist/**/*.js",
+    "dist/**/*.d.ts"
+  ],
+  "scripts": {
+    "build": "node --max-old-space-size=4096 node_modules/typescript/bin/tsc",
+    "dev": "node --max-old-space-size=4096 node_modules/typescript/bin/tsc --watch",
+    "start": "node dist/index.js",
+    "test": "vitest run",
+    "prepublishOnly": "npm run build"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/the-answerai/answer-engine.git",
+    "directory": "packages/mcp-server"
+  },
+  "keywords": [
+    "answer-engine",
+    "mcp",
+    "model-context-protocol",
+    "search",
+    "ai"
+  ],
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.12.1",
+    "zod": "^3.22.4"
+  },
+  "devDependencies": {
+    "typescript": "^5.3.3",
+    "@types/node": "^20.10.5",
+    "vitest": "^1.0.4"
+  }
+}