attio-mcp 1.3.6 → 1.4.1

package/dist/services/skill-generator/SchemaFormatterService.js

@@ -0,0 +1,168 @@
+/**
+ * Service for formatting workspace schemas into various output formats
+ *
+ * Uses Handlebars templates to transform WorkspaceSchema objects into:
+ * - Claude Skills (SKILL.md + resources/)
+ * - Plain Markdown (single file)
+ * - JSON (machine-readable)
+ *
+ * @see Issue #983
+ */
+import Handlebars from 'handlebars';
+import * as fs from 'fs/promises';
+import * as path from 'path';
+import { fileURLToPath } from 'url';
+// Get __dirname equivalent in ES modules
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+/**
+ * Service for formatting workspace schemas into various output formats
+ */
+export class SchemaFormatterService {
+    templates = new Map();
+    helpersRegistered = false;
+    constructor() {
+        this.registerHelpers();
+    }
+    /**
+     * Formats schema to specified output format
+     *
+     * @param schema - Complete workspace schema
+     * @param format - Output format (skill, markdown, json)
+     * @returns Formatted output ready for writing
+     */
+    async format(schema, format) {
+        switch (format) {
+            case 'skill':
+                return this.formatAsSkill(schema);
+            case 'markdown':
+                return this.formatAsMarkdown(schema);
+            case 'json':
+                return this.formatAsJSON(schema);
+            default:
+                throw new Error(`Unsupported format: ${format}`);
+        }
+    }
+    /**
+     * Formats as Claude Skill with SKILL.md + resources/
+     *
+     * @param schema - Workspace schema
+     * @returns Skill files ready for writing
+     */
+    async formatAsSkill(schema) {
+        const skillMd = await this.renderTemplate('SKILL.template.md', schema);
+        // Validate Claude Skill description length requirement (≤200 chars)
+        const descMatch = skillMd.match(/^description:\s*(.+)$/m);
+        if (descMatch && descMatch[1].length > 200) {
+            throw new Error(`Skill description exceeds 200 characters (${descMatch[1].length} chars). ` +
+                `Claude Skills require descriptions ≤200 chars. ` +
+                `Try reducing the number of objects or simplifying the description.`);
+        }
+        // Validate Claude Skill name length requirement (≤64 chars)
+        const nameMatch = skillMd.match(/^name:\s*(.+)$/m);
+        if (nameMatch && nameMatch[1].trim().length > 64) {
+            throw new Error(`Skill name exceeds 64 characters (${nameMatch[1].trim().length} chars). ` +
+                `Claude Skills require names ≤64 chars.`);
+        }
+        // Generate per-object attribute files for progressive disclosure
+        // This enables Claude to load only the object it's working with (~2k tokens)
+        // instead of the entire monolithic file (~10k tokens)
+        // @see Issue #1014
+        const attributeFiles = {};
+        for (const obj of schema.objects) {
+            const objectSchema = { ...schema, objects: [obj] };
+            const attrMd = await this.renderTemplate('attribute-reference.template.md', objectSchema);
+            attributeFiles[`resources/${obj.objectSlug}-attributes.md`] = attrMd;
+        }
+        const complexTypes = await this.renderTemplate('complex-types.template.md', schema);
+        return {
+            format: 'skill',
+            files: {
+                'SKILL.md': skillMd,
+                ...attributeFiles,
+                'resources/complex-types.md': complexTypes,
+            },
+        };
+    }
+    /**
+     * Formats as single markdown file (all-in-one)
+     *
+     * @param schema - Workspace schema
+     * @returns Single markdown file
+     */
+    async formatAsMarkdown(schema) {
+        // Render all templates and combine them
+        const skillMd = await this.renderTemplate('SKILL.template.md', schema);
+        const attrRef = await this.renderTemplate('attribute-reference.template.md', schema);
+        const complexTypes = await this.renderTemplate('complex-types.template.md', schema);
+        // Combine into single document
+        const combined = `${skillMd}\n\n---\n\n${attrRef}\n\n---\n\n${complexTypes}`;
+        return {
+            format: 'markdown',
+            files: {
+                'attio-workspace-schema.md': combined,
+            },
+        };
+    }
+    /**
+     * Formats as JSON (machine-readable)
+     *
+     * @param schema - Workspace schema
+     * @returns JSON representation
+     */
+    formatAsJSON(schema) {
+        return {
+            format: 'json',
+            files: {
+                'attio-workspace-schema.json': JSON.stringify(schema, null, 2),
+            },
+        };
+    }
+    /**
+     * Renders a template with the given data
+     *
+     * @param templateName - Template filename
+     * @param data - Data to pass to template
+     * @returns Rendered template string
+     */
+    async renderTemplate(templateName, data) {
+        // Check cache first
+        if (!this.templates.has(templateName)) {
+            // Load and compile template
+            const templatePath = path.join(__dirname, '../../templates/skill', templateName);
+            try {
+                const templateSource = await fs.readFile(templatePath, 'utf8');
+                const compiledTemplate = Handlebars.compile(templateSource);
+                this.templates.set(templateName, compiledTemplate);
+            }
+            catch (error) {
+                throw new Error(`Failed to load template ${templateName}: ${error instanceof Error ? error.message : String(error)}`);
+            }
+        }
+        // Render template
+        const template = this.templates.get(templateName);
+        return template(data);
+    }
+    /**
+     * Registers custom Handlebars helpers
+     */
+    registerHelpers() {
+        if (this.helpersRegistered) {
+            return;
+        }
+        // Helper: Display checkmark or X for boolean values
+        Handlebars.registerHelper('checkmark', (value) => {
+            return value ? '✓' : '✗';
+        });
+        // Helper: Subtract two numbers
+        Handlebars.registerHelper('subtract', (a, b) => {
+            return a - b;
+        });
+        // Helper: JSON stringify with formatting
+        Handlebars.registerHelper('json', (obj) => {
+            return JSON.stringify(obj, null, 2);
+        });
+        this.helpersRegistered = true;
+    }
+}
+//# sourceMappingURL=SchemaFormatterService.js.map

package/dist/services/skill-generator/SchemaFormatterService.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"SchemaFormatterService.js","sourceRoot":"","sources":["../../../src/services/skill-generator/SchemaFormatterService.ts"],"names":[],"mappings":"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"}

package/dist/services/skill-generator/WorkspaceSchemaService.d.ts

@@ -0,0 +1,84 @@
+/**
+ * Service for fetching and aggregating Attio workspace schema data
+ *
+ * This service orchestrates calls to existing services to build a complete
+ * workspace schema including objects, attributes, select options, and metadata.
+ *
+ * @see Issue #983
+ */
+import type { WorkspaceSchema, FetchSchemaOptions } from './types.js';
+/**
+ * Service for fetching complete workspace schema data
+ *
+ * Note: API key flows through getLazyAttioClient() from environment/context,
+ * not through constructor dependency injection.
+ */
+export declare class WorkspaceSchemaService {
+    /**
+     * Creates a new WorkspaceSchemaService
+     */
+    constructor();
+    /**
+     * Fetches the display title for an object from the Attio API
+     *
+     * @param objectSlug - Object API slug (e.g., 'companies', 'custom_prospecting_list')
+     * @returns The object title from Attio, or null if fetch fails
+     * @see Issue #1017
+     */
+    private fetchObjectTitle;
+    private getOptionFetchDelayMs;
+    /**
+     * Fetches complete workspace schema for specified objects
+     *
+     * This method implements graceful degradation:
+     * - If an object fails to fetch, it logs the error and continues with other objects
+     * - If an attribute's options fail to fetch, it includes the attribute without options
+     *
+     * @param objectSlugs - Array of object slugs to fetch (e.g., ['companies', 'people'])
+     * @param options - Fetching options (max options, include archived)
+     * @returns Complete workspace schema
+     */
+    fetchSchema(objectSlugs: string[], options: FetchSchemaOptions): Promise<WorkspaceSchema>;
+    /**
+     * Fetches schema for a single object
+     *
+     * @param objectSlug - Object slug (e.g., 'companies', 'people', 'deals')
+     * @param options - Fetching options
+     * @returns Object schema with all attributes and metadata
+     */
+    private fetchObjectSchema;
+    /**
+     * Checks if an attribute type supports options (select, status, multi-select)
+     *
+     * @param type - Attribute type from Attio API
+     * @returns True if attribute supports options
+     */
+    private isOptionBasedAttribute;
+    /**
+     * Checks if an attribute type is a complex type requiring structure documentation
+     *
+     * @param type - Attribute type from Attio API
+     * @returns True if attribute is a complex type
+     */
+    private isComplexType;
+    /**
+     * Gets the structure definition for complex attribute types
+     *
+     * @param type - Complex attribute type
+     * @returns Structure definition with field types
+     */
+    private getComplexTypeStructure;
+    /**
+     * Gets human-readable display name for an object slug
+     *
+     * Uses the fetched title from Attio API if available, otherwise falls back
+     * to hardcoded display names for Phase 1 objects or slug capitalization.
+     *
+     * @param objectSlug - Object API slug
+     * @param fetchedTitle - Title fetched from Attio API (optional)
+     * @returns Human-readable display name
+     * @see Issue #1017
+     */
+    private getDisplayName;
+}
+//# sourceMappingURL=WorkspaceSchemaService.d.ts.map

package/dist/services/skill-generator/WorkspaceSchemaService.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"WorkspaceSchemaService.d.ts","sourceRoot":"","sources":["../../../src/services/skill-generator/WorkspaceSchemaService.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAUH,OAAO,KAAK,EACV,eAAe,EAGf,kBAAkB,EACnB,MAAM,YAAY,CAAC;AAsCpB;;;;;GAKG;AACH,qBAAa,sBAAsB;IACjC;;OAEG;;IAKH;;;;;;OAMG;YACW,gBAAgB;IAgB9B,OAAO,CAAC,qBAAqB;IAa7B;;;;;;;;;;OAUG;IACG,WAAW,CACf,WAAW,EAAE,MAAM,EAAE,EACrB,OAAO,EAAE,kBAAkB,GAC1B,OAAO,CAAC,eAAe,CAAC;IA4B3B;;;;;;OAMG;YACW,iBAAiB;IA2G/B;;;;;OAKG;IACH,OAAO,CAAC,sBAAsB;IAI9B;;;;;OAKG;IACH,OAAO,CAAC,aAAa;IASrB;;;;;OAKG;IACH,OAAO,CAAC,uBAAuB;IA0C/B;;;;;;;;;;OAUG;IACH,OAAO,CAAC,cAAc;CAyBvB"}

package/dist/services/skill-generator/WorkspaceSchemaService.js

@@ -0,0 +1,292 @@
+/**
+ * Service for fetching and aggregating Attio workspace schema data
+ *
+ * This service orchestrates calls to existing services to build a complete
+ * workspace schema including objects, attributes, select options, and metadata.
+ *
+ * @see Issue #983
+ */
+import { getObjectAttributeMetadata } from '../../api/attribute-types.js';
+import { getLazyAttioClient } from '../../api/lazy-client.js';
+import { AttributeOptionsService } from '../../services/metadata/AttributeOptionsService.js';
+import { debug as logDebug, error as logError, warn as logWarn, } from '../../utils/logger.js';
+/**
+ * Type guard to check if an ID is a nested option ID object
+ * Attio API returns option IDs as nested objects: {workspace_id, object_id, attribute_id, option_id}
+ * @param id - The ID value to check
+ * @returns True if the ID is a nested option ID object
+ * @see Issue #1014
+ */
+function isNestedOptionId(id) {
+    return typeof id === 'object' && id !== null && 'option_id' in id;
+}
+/**
+ * Generates a slug-style value from an option title
+ * Converts "Existing Customer" → "existing_customer"
+ * @param title - The option title
+ * @returns Slug-style value
+ * @see Issue #1014
+ */
+function generateOptionValue(title) {
+    return title
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, '_') // Replace non-alphanumeric with underscore
+        .replace(/^_+|_+$/g, ''); // Trim leading/trailing underscores
+}
+/**
+ * Service for fetching complete workspace schema data
+ *
+ * Note: API key flows through getLazyAttioClient() from environment/context,
+ * not through constructor dependency injection.
+ */
+export class WorkspaceSchemaService {
+    /**
+     * Creates a new WorkspaceSchemaService
+     */
+    constructor() {
+        // No parameters needed - API key flows through getLazyAttioClient()
+    }
+    /**
+     * Fetches the display title for an object from the Attio API
+     *
+     * @param objectSlug - Object API slug (e.g., 'companies', 'custom_prospecting_list')
+     * @returns The object title from Attio, or null if fetch fails
+     * @see Issue #1017
+     */
+    async fetchObjectTitle(objectSlug) {
+        try {
+            const client = getLazyAttioClient();
+            const response = await client.get(`/objects/${objectSlug}`);
+            const obj = response?.data?.data || response?.data;
+            return obj?.title || null;
+        }
+        catch {
+            logDebug('WorkspaceSchemaService', `Could not fetch title for ${objectSlug}, using fallback`, { objectSlug });
+            return null;
+        }
+    }
+    getOptionFetchDelayMs(options) {
+        const optionFetchDelayMs = options.optionFetchDelayMs;
+        if (optionFetchDelayMs === undefined)
+            return 100;
+        if (typeof optionFetchDelayMs !== 'number' ||
+            !Number.isFinite(optionFetchDelayMs) ||
+            optionFetchDelayMs < 0) {
+            return 100;
+        }
+        return optionFetchDelayMs;
+    }
+    /**
+     * Fetches complete workspace schema for specified objects
+     *
+     * This method implements graceful degradation:
+     * - If an object fails to fetch, it logs the error and continues with other objects
+     * - If an attribute's options fail to fetch, it includes the attribute without options
+     *
+     * @param objectSlugs - Array of object slugs to fetch (e.g., ['companies', 'people'])
+     * @param options - Fetching options (max options, include archived)
+     * @returns Complete workspace schema
+     */
+    async fetchSchema(objectSlugs, options) {
+        const objects = [];
+        for (const objectSlug of objectSlugs) {
+            try {
+                const objectSchema = await this.fetchObjectSchema(objectSlug, options);
+                objects.push(objectSchema);
+            }
+            catch (error) {
+                logError('WorkspaceSchemaService', `Failed to fetch schema for ${objectSlug}`, error instanceof Error ? error : new Error(String(error)), { objectSlug });
+                // Continue processing other objects despite error
+            }
+        }
+        return {
+            metadata: {
+                generatedAt: new Date().toISOString(),
+                workspace: 'attio', // Could be enhanced to fetch actual workspace name
+                objects: objectSlugs,
+            },
+            objects,
+        };
+    }
+    /**
+     * Fetches schema for a single object
+     *
+     * @param objectSlug - Object slug (e.g., 'companies', 'people', 'deals')
+     * @param options - Fetching options
+     * @returns Object schema with all attributes and metadata
+     */
+    async fetchObjectSchema(objectSlug, options) {
+        const optionFetchDelayMs = this.getOptionFetchDelayMs(options);
+        const PHASE1_OBJECTS = ['companies', 'people', 'deals'];
+        // 1. Fetch object title from API for custom objects (Issue #1017)
+        // Skip API call for Phase 1 objects - they have hardcoded display names
+        const objectTitle = PHASE1_OBJECTS.includes(objectSlug)
+            ? null
+            : await this.fetchObjectTitle(objectSlug);
+        // 2. Fetch attribute metadata (uses existing 15min TTL cache)
+        const metadataMap = await getObjectAttributeMetadata(objectSlug);
+        // 3. Convert metadata to AttributeSchema array
+        const attributes = [];
+        for (const [apiSlug, metadata] of metadataMap.entries()) {
+            const attributeSchema = {
+                apiSlug,
+                displayName: metadata.title,
+                type: metadata.type,
+                isMultiselect: metadata.is_multiselect || false,
+                isUnique: metadata.is_unique || false,
+                isRequired: metadata.is_required || false,
+                isWritable: metadata.is_writable !== false, // Default to true
+                description: metadata.description,
+            };
+            // 4. Fetch options for select/status attributes
+            if (this.isOptionBasedAttribute(metadata.type)) {
+                try {
+                    const optionsResult = await AttributeOptionsService.getOptions(objectSlug, apiSlug, options.includeArchived);
+                    // Apply truncation
+                    const totalOptions = optionsResult.options.length;
+                    const truncated = totalOptions > options.maxOptionsPerAttribute;
+                    attributeSchema.options = optionsResult.options
+                        .slice(0, options.maxOptionsPerAttribute)
+                        .map((opt) => ({
+                        // Handle nested ID objects from Attio API
+                        // API returns: { workspace_id, object_id, attribute_id, option_id }
+                        id: isNestedOptionId(opt.id)
+                            ? opt.id.option_id
+                            : typeof opt.id === 'string'
+                                ? opt.id
+                                : '',
+                        title: opt.title,
+                        // Generate slug-style value from title since Attio API doesn't provide it
+                        // "Existing Customer" → "existing_customer"
+                        value: generateOptionValue(opt.title),
+                        isArchived: 'is_archived' in opt ? opt.is_archived : false,
+                    }));
+                    attributeSchema.optionsTruncated = truncated;
+                    attributeSchema.totalOptions = totalOptions;
+                    // Rate limiting: Add delay between option fetches
+                    if (optionFetchDelayMs > 0) {
+                        await new Promise((resolve) => setTimeout(resolve, optionFetchDelayMs));
+                    }
+                }
+                catch (error) {
+                    // Log warning but don't fail - attribute can still be documented
+                    const errorMessage = error instanceof Error ? error.message : String(error);
+                    logWarn('WorkspaceSchemaService', `No options available for ${objectSlug}.${apiSlug}`, { objectSlug, attributeSlug: apiSlug, errorMessage });
+                }
+            }
+            // 5. Add complex type structures
+            if (this.isComplexType(metadata.type)) {
+                attributeSchema.complexTypeStructure = this.getComplexTypeStructure(metadata.type);
+            }
+            // 6. Add relationship metadata (only when we have real data)
+            if (metadata.relationship?.object && metadata.relationship?.cardinality) {
+                attributeSchema.relationship = {
+                    targetObject: metadata.relationship.object,
+                    cardinality: metadata.relationship.cardinality,
+                };
+            }
+            attributes.push(attributeSchema);
+        }
+        return {
+            objectSlug,
+            displayName: this.getDisplayName(objectSlug, objectTitle),
+            attributes,
+        };
+    }
+    /**
+     * Checks if an attribute type supports options (select, status, multi-select)
+     *
+     * @param type - Attribute type from Attio API
+     * @returns True if attribute supports options
+     */
+    isOptionBasedAttribute(type) {
+        return ['select', 'status', 'multi-select'].includes(type);
+    }
+    /**
+     * Checks if an attribute type is a complex type requiring structure documentation
+     *
+     * @param type - Attribute type from Attio API
+     * @returns True if attribute is a complex type
+     */
+    isComplexType(type) {
+        return [
+            'location',
+            'personal-name',
+            'phone-number',
+            'email-address',
+        ].includes(type);
+    }
+    /**
+     * Gets the structure definition for complex attribute types
+     *
+     * @param type - Complex attribute type
+     * @returns Structure definition with field types
+     */
+    getComplexTypeStructure(type) {
+        switch (type) {
+            case 'location':
+                return {
+                    line_1: 'string | null (street address)',
+                    line_2: 'string | null (apt/suite)',
+                    line_3: 'string | null (additional)',
+                    line_4: 'string | null (additional)',
+                    locality: 'string | null (city)',
+                    region: 'string | null (state/province)',
+                    postcode: 'string | null (ZIP/postal code)',
+                    country_code: 'string | null (ISO country code)',
+                    latitude: 'number | null (coordinates)',
+                    longitude: 'number | null (coordinates)',
+                };
+            case 'personal-name':
+                return {
+                    first_name: 'string (required)',
+                    last_name: 'string | null',
+                    middle_name: 'string | null',
+                    title: 'string | null (e.g., "Dr.", "Prof.")',
+                    full_name: 'string (auto-generated, read-only)',
+                };
+            case 'phone-number':
+                return {
+                    country_code: 'string (e.g., "+1")',
+                    number: 'string (digits only)',
+                    original_number: 'string (as provided)',
+                };
+            case 'email-address':
+                return {
+                    email_address: 'string (valid email format)',
+                };
+            default:
+                return {};
+        }
+    }
+    /**
+     * Gets human-readable display name for an object slug
+     *
+     * Uses the fetched title from Attio API if available, otherwise falls back
+     * to hardcoded display names for Phase 1 objects or slug capitalization.
+     *
+     * @param objectSlug - Object API slug
+     * @param fetchedTitle - Title fetched from Attio API (optional)
+     * @returns Human-readable display name
+     * @see Issue #1017
+     */
+    getDisplayName(objectSlug, fetchedTitle) {
+        // Use API-fetched title if available
+        if (fetchedTitle) {
+            return fetchedTitle;
+        }
+        // Fallback to hardcoded display names for Phase 1 objects
+        const displayNames = {
+            companies: 'Companies',
+            people: 'People',
+            deals: 'Deals',
+        };
+        // If not in map, title-case the slug (replace underscores with spaces)
+        return (displayNames[objectSlug] ||
+            objectSlug
+                .split('_')
+                .map((word) => word.charAt(0).toUpperCase() + word.slice(1))
+                .join(' '));
+    }
+}
+//# sourceMappingURL=WorkspaceSchemaService.js.map

package/dist/services/skill-generator/WorkspaceSchemaService.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"WorkspaceSchemaService.js","sourceRoot":"","sources":["../../../src/services/skill-generator/WorkspaceSchemaService.ts"],"names":[],"mappings":"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"}

package/dist/services/skill-generator/index.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Workspace Schema Skill Generator
+ *
+ * Exports services and types for generating Claude Skills from Attio workspace schemas.
+ *
+ * @see Issue #983
+ */
+export { WorkspaceSchemaService } from './WorkspaceSchemaService.js';
+export { SchemaFormatterService } from './SchemaFormatterService.js';
+export { OutputWriterService } from './OutputWriterService.js';
+export type { GenerateSkillConfig, WorkspaceSchema, ObjectSchema, AttributeSchema, AttributeOption, FormattedOutput, SkillOutput, FetchSchemaOptions, } from './types.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/services/skill-generator/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/services/skill-generator/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAE,sBAAsB,EAAE,MAAM,6BAA6B,CAAC;AACrE,OAAO,EAAE,sBAAsB,EAAE,MAAM,6BAA6B,CAAC;AACrE,OAAO,EAAE,mBAAmB,EAAE,MAAM,0BAA0B,CAAC;AAC/D,YAAY,EACV,mBAAmB,EACnB,eAAe,EACf,YAAY,EACZ,eAAe,EACf,eAAe,EACf,eAAe,EACf,WAAW,EACX,kBAAkB,GACnB,MAAM,YAAY,CAAC"}

package/dist/services/skill-generator/index.js

@@ -0,0 +1,11 @@
+/**
+ * Workspace Schema Skill Generator
+ *
+ * Exports services and types for generating Claude Skills from Attio workspace schemas.
+ *
+ * @see Issue #983
+ */
+export { WorkspaceSchemaService } from './WorkspaceSchemaService.js';
+export { SchemaFormatterService } from './SchemaFormatterService.js';
+export { OutputWriterService } from './OutputWriterService.js';
+//# sourceMappingURL=index.js.map

package/dist/services/skill-generator/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/services/skill-generator/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAE,sBAAsB,EAAE,MAAM,6BAA6B,CAAC;AACrE,OAAO,EAAE,sBAAsB,EAAE,MAAM,6BAA6B,CAAC;AACrE,OAAO,EAAE,mBAAmB,EAAE,MAAM,0BAA0B,CAAC"}