@zincapp/mcp-server 1.0.0

package/dist/client.d.ts

@@ -0,0 +1,8 @@
+import type { McpConfig } from './config.js';
+export declare class ZincAppClient {
+    private baseUrl;
+    private token;
+    constructor(config: McpConfig);
+    get<T>(path: string): Promise<T>;
+    post<T>(path: string, body?: unknown): Promise<T>;
+}

package/dist/client.js

@@ -0,0 +1,39 @@
+export class ZincAppClient {
+    baseUrl;
+    token;
+    constructor(config) {
+        this.baseUrl = config.apiBaseUrl.replace(/\/$/, '');
+        this.token = config.agentToken;
+    }
+    async get(path) {
+        const url = `${this.baseUrl}/agent/v1${path}`;
+        const res = await fetch(url, {
+            headers: {
+                'Authorization': `Bearer ${this.token}`,
+                'Accept': 'application/json',
+            },
+        });
+        if (!res.ok) {
+            const body = await res.text();
+            throw new Error(`API error ${res.status}: ${body}`);
+        }
+        return res.json();
+    }
+    async post(path, body) {
+        const url = `${this.baseUrl}/agent/v1${path}`;
+        const res = await fetch(url, {
+            method: 'POST',
+            headers: {
+                'Authorization': `Bearer ${this.token}`,
+                'Accept': 'application/json',
+                'Content-Type': 'application/json',
+            },
+            body: body ? JSON.stringify(body) : undefined,
+        });
+        if (!res.ok) {
+            const text = await res.text();
+            throw new Error(`API error ${res.status}: ${text}`);
+        }
+        return res.json();
+    }
+}

package/dist/config.d.ts

@@ -0,0 +1,9 @@
+export interface McpConfig {
+    agentToken: string;
+    apiBaseUrl: string;
+}
+/**
+ * Loads config from environment variables, then falls back to .zincapp.json
+ * in the current directory or home directory.
+ */
+export declare function loadConfig(): McpConfig;

package/dist/config.js

@@ -0,0 +1,41 @@
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import * as os from 'node:os';
+/**
+ * Loads config from environment variables, then falls back to .zincapp.json
+ * in the current directory or home directory.
+ */
+export function loadConfig() {
+    // Environment variables take precedence
+    let agentToken = process.env.ZINCAPP_AGENT_TOKEN || '';
+    let apiBaseUrl = process.env.ZINCAPP_API_URL || '';
+    // Try .zincapp.json if env vars missing
+    if (!agentToken) {
+        const configPaths = [
+            path.join(process.cwd(), '.zincapp.json'),
+            path.join(os.homedir(), '.zincapp.json'),
+        ];
+        for (const configPath of configPaths) {
+            try {
+                const raw = fs.readFileSync(configPath, 'utf-8');
+                const parsed = JSON.parse(raw);
+                if (!agentToken && parsed.agentToken)
+                    agentToken = parsed.agentToken;
+                if (!apiBaseUrl && parsed.apiUrl)
+                    apiBaseUrl = parsed.apiUrl;
+                break;
+            }
+            catch {
+                // File doesn't exist or invalid JSON — continue
+            }
+        }
+    }
+    if (!agentToken) {
+        throw new Error('ZINCAPP_AGENT_TOKEN not set. Configure via environment variable or .zincapp.json file.\n' +
+            'Create a token at: https://developers.zincapp.com/agent-tokens');
+    }
+    return {
+        agentToken,
+        apiBaseUrl: apiBaseUrl || 'https://api.zincapp.com/api',
+    };
+}

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/index.js

@@ -0,0 +1,23 @@
+#!/usr/bin/env node
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { loadConfig } from './config.js';
+import { ZincAppClient } from './client.js';
+import { registerAllTools } from './tools/index.js';
+import { registerAllResources } from './resources/index.js';
+async function main() {
+    const config = loadConfig();
+    const client = new ZincAppClient(config);
+    const server = new McpServer({
+        name: 'zincapp',
+        version: '1.0.0',
+    });
+    registerAllTools(server, client);
+    registerAllResources(server, client);
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+}
+main().catch((err) => {
+    console.error('Failed to start ZincApp MCP server:', err.message || err);
+    process.exit(1);
+});

package/dist/resources/index.d.ts

@@ -0,0 +1,3 @@
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import type { ZincAppClient } from '../client.js';
+export declare function registerAllResources(server: McpServer, client: ZincAppClient): void;

package/dist/resources/index.js

@@ -0,0 +1,19 @@
+export function registerAllResources(server, client) {
+    server.resource('docs-index', 'docs://index', async (uri) => {
+        const docs = await client.get('/docs?limit=200');
+        const text = docs.length === 0
+            ? 'No documentation available.'
+            : [
+                '# ZincApp Documentation Index',
+                '',
+                ...docs.map(d => `- **${d.title}** (\`${d.id}\`): ${d.aiSummary || d.description}`),
+            ].join('\n');
+        return {
+            contents: [{
+                    uri: uri.href,
+                    mimeType: 'text/markdown',
+                    text,
+                }],
+        };
+    });
+}

package/dist/tools/get-contract.d.ts

@@ -0,0 +1,3 @@
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import type { ZincAppClient } from '../client.js';
+export declare function registerGetContract(server: McpServer, client: ZincAppClient): void;

package/dist/tools/get-contract.js

@@ -0,0 +1,21 @@
+import { z } from 'zod';
+export function registerGetContract(server, client) {
+    server.tool('get_contract_spec', 'Get details about a specific integration contract, including its API spec and terms.', { contractId: z.number().describe('Contract ID') }, async ({ contractId }) => {
+        const contract = await client.get(`/contracts/${contractId}`);
+        const parts = [
+            `# ${contract.title} (v${contract.version})`,
+            '',
+            `**Status:** ${contract.status}`,
+        ];
+        if (contract.description) {
+            parts.push('', contract.description);
+        }
+        if (contract.terms) {
+            parts.push('', '## Terms', '', contract.terms);
+        }
+        if (contract.spec) {
+            parts.push('', '## API Spec', '', '```json', contract.spec, '```');
+        }
+        return { content: [{ type: 'text', text: parts.join('\n') }] };
+    });
+}

package/dist/tools/get-endpoint.d.ts

@@ -0,0 +1,3 @@
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import type { ZincAppClient } from '../client.js';
+export declare function registerGetEndpoint(server: McpServer, client: ZincAppClient): void;

package/dist/tools/get-endpoint.js

@@ -0,0 +1,18 @@
+import { z } from 'zod';
+export function registerGetEndpoint(server, client) {
+    server.tool('get_api_endpoint', 'Get details about a specific API endpoint by method and path.', {
+        method: z.enum(['GET', 'POST', 'PUT', 'DELETE']).describe('HTTP method'),
+        path: z.string().describe('API path (e.g. "/containers")'),
+    }, async ({ method, path }) => {
+        const encodedPath = path.startsWith('/') ? path.substring(1) : path;
+        const detail = await client.get(`/reference/endpoints/${method}/${encodedPath}`);
+        const text = [
+            `## ${detail.method} ${detail.path}`,
+            '',
+            `**Summary:** ${detail.summary}`,
+            `**Auth:** ${detail.auth}`,
+            `**Category:** ${detail.category}`,
+        ].join('\n');
+        return { content: [{ type: 'text', text }] };
+    });
+}

package/dist/tools/index.d.ts

@@ -0,0 +1,3 @@
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import type { ZincAppClient } from '../client.js';
+export declare function registerAllTools(server: McpServer, client: ZincAppClient): void;

package/dist/tools/index.js

@@ -0,0 +1,16 @@
+import { registerSearchDocs } from './search-docs.js';
+import { registerReadDoc } from './read-doc.js';
+import { registerListDocs } from './list-docs.js';
+import { registerListEndpoints } from './list-endpoints.js';
+import { registerGetEndpoint } from './get-endpoint.js';
+import { registerSandboxRequest } from './sandbox-request.js';
+import { registerGetContract } from './get-contract.js';
+export function registerAllTools(server, client) {
+    registerSearchDocs(server, client);
+    registerReadDoc(server, client);
+    registerListDocs(server, client);
+    registerListEndpoints(server, client);
+    registerGetEndpoint(server, client);
+    registerSandboxRequest(server, client);
+    registerGetContract(server, client);
+}

package/dist/tools/list-docs.d.ts

@@ -0,0 +1,3 @@
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import type { ZincAppClient } from '../client.js';
+export declare function registerListDocs(server: McpServer, client: ZincAppClient): void;

package/dist/tools/list-docs.js

@@ -0,0 +1,9 @@
+export function registerListDocs(server, client) {
+    server.tool('list_docs', 'List all available ZincApp developer documentation with titles and summaries.', {}, async () => {
+        const docs = await client.get('/docs?limit=200');
+        const text = docs.length === 0
+            ? 'No documentation available.'
+            : docs.map(d => `- **${d.title}** (\`${d.id}\`): ${d.aiSummary || d.description}`).join('\n');
+        return { content: [{ type: 'text', text }] };
+    });
+}

package/dist/tools/list-endpoints.d.ts

@@ -0,0 +1,3 @@
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import type { ZincAppClient } from '../client.js';
+export declare function registerListEndpoints(server: McpServer, client: ZincAppClient): void;

package/dist/tools/list-endpoints.js

@@ -0,0 +1,25 @@
+export function registerListEndpoints(server, client) {
+    server.tool('list_api_endpoints', 'List all ZincApp API endpoints available to your integration. Groups by category.', {}, async () => {
+        const endpoints = await client.get('/reference/endpoints');
+        if (endpoints.length === 0) {
+            return { content: [{ type: 'text', text: 'No API endpoints available. You may need an accepted contract.' }] };
+        }
+        // Group by category
+        const grouped = new Map();
+        for (const ep of endpoints) {
+            const cat = ep.category || 'General';
+            if (!grouped.has(cat))
+                grouped.set(cat, []);
+            grouped.get(cat).push(ep);
+        }
+        let text = '';
+        for (const [category, eps] of grouped) {
+            text += `## ${category}\n\n`;
+            for (const ep of eps) {
+                text += `- \`${ep.method} ${ep.path}\` — ${ep.summary} (auth: ${ep.auth})\n`;
+            }
+            text += '\n';
+        }
+        return { content: [{ type: 'text', text: text.trim() }] };
+    });
+}

package/dist/tools/read-doc.d.ts

@@ -0,0 +1,3 @@
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import type { ZincAppClient } from '../client.js';
+export declare function registerReadDoc(server: McpServer, client: ZincAppClient): void;

package/dist/tools/read-doc.js

@@ -0,0 +1,8 @@
+import { z } from 'zod';
+export function registerReadDoc(server, client) {
+    server.tool('read_doc', 'Read a specific ZincApp documentation page by its ID. Returns the full markdown content.', { docId: z.string().describe('Document ID (e.g. "api.overview")') }, async ({ docId }) => {
+        const doc = await client.get(`/docs/${encodeURIComponent(docId)}`);
+        const text = `# ${doc.title}\n\n${doc.markdown}`;
+        return { content: [{ type: 'text', text }] };
+    });
+}

package/dist/tools/sandbox-request.d.ts

@@ -0,0 +1,3 @@
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import type { ZincAppClient } from '../client.js';
+export declare function registerSandboxRequest(server: McpServer, client: ZincAppClient): void;

package/dist/tools/sandbox-request.js

@@ -0,0 +1,22 @@
+import { z } from 'zod';
+export function registerSandboxRequest(server, client) {
+    server.tool('sandbox_api_request', 'Execute a test API call in the ZincApp sandbox environment. Only works with the SANDBOX_API scope.', {
+        method: z.enum(['GET', 'POST', 'PUT', 'DELETE']).describe('HTTP method'),
+        path: z.string().describe('API path to call (e.g. "/containers")'),
+        body: z.string().optional().describe('Request body as JSON string (for POST/PUT)'),
+    }, async ({ method, path, body }) => {
+        const result = await client.post('/sandbox/relay', {
+            method,
+            path,
+            body: body || null,
+        });
+        const text = [
+            `**Status:** ${result.status}`,
+            '',
+            '```json',
+            result.body || '(empty)',
+            '```',
+        ].join('\n');
+        return { content: [{ type: 'text', text }] };
+    });
+}

package/dist/tools/search-docs.d.ts

@@ -0,0 +1,3 @@
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import type { ZincAppClient } from '../client.js';
+export declare function registerSearchDocs(server: McpServer, client: ZincAppClient): void;

package/dist/tools/search-docs.js

@@ -0,0 +1,10 @@
+import { z } from 'zod';
+export function registerSearchDocs(server, client) {
+    server.tool('search_docs', 'Search ZincApp developer documentation by keyword. Returns matching documents ranked by relevance.', { query: z.string().describe('Search query'), limit: z.number().optional().describe('Max results (default 10)') }, async ({ query, limit }) => {
+        const results = await client.get(`/docs/search?q=${encodeURIComponent(query)}&limit=${limit || 10}`);
+        const text = results.length === 0
+            ? 'No documents found matching your query.'
+            : results.map(r => `## ${r.title}\n- ID: \`${r.id}\`\n- ${r.aiSummary || r.description}\n- Relevance: ${r.relevance.toFixed(2)}`).join('\n\n');
+        return { content: [{ type: 'text', text }] };
+    });
+}

package/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "@zincapp/mcp-server",
+  "version": "1.0.0",
+  "description": "MCP server for ZincApp Developer Portal — enables AI coding assistants to search docs, read API reference, and execute sandbox API calls",
+  "type": "module",
+  "bin": {
+    "zincapp-mcp-server": "./dist/index.js"
+  },
+  "main": "./dist/index.js",
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch",
+    "start": "node dist/index.js"
+  },
+  "keywords": [
+    "mcp",
+    "zincapp",
+    "developer-portal",
+    "ai-agent",
+    "claude-code"
+  ],
+  "license": "MIT",
+  "private": false,
+  "files": [
+    "dist"
+  ],
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.12.0",
+    "zod": "^3.23.0"
+  },
+  "devDependencies": {
+    "typescript": "^5.6.0",
+    "@types/node": "^22.0.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/vidaldiego/zincapp-mcp-server"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=18"
+  }
+}