Stampchain MCP Server

Instructions

Implementation Reference

• src/tools/collections.ts:24-183 (handler)

  The GetCollectionTool class implements the core logic for the 'get_collection' tool. It validates input, calls the Stampchain API (using searchCollections as fallback), formats collection information and optional stamps into a table, and returns a multi-part response including text summary and JSON data.
  export class GetCollectionTool extends BaseTool< z.input<typeof GetCollectionParamsSchema>, GetCollectionParams > { public readonly name = 'get_collection'; public readonly description = 'Retrieve detailed information about a specific stamp collection by its ID'; public readonly inputSchema: MCPTool['inputSchema'] = { type: 'object', properties: { collection_id: { type: 'string', description: 'The ID of the collection to retrieve', }, include_stamps: { type: 'boolean', description: 'Whether to include stamps in the collection', default: false, }, stamps_page: { type: 'number', description: 'Page number for stamps if included', minimum: 1, default: 1, }, stamps_limit: { type: 'number', description: 'Number of stamps per page', minimum: 1, maximum: 100, default: 20, }, }, required: ['collection_id'], }; public readonly schema = GetCollectionParamsSchema; public readonly metadata = { version: '1.0.0', tags: ['collections', 'query'], requiresNetwork: true, apiDependencies: ['stampchain'], }; private apiClient: StampchainClient; constructor(apiClient?: StampchainClient) { super(); this.apiClient = apiClient || new StampchainClient(); } public async execute(params: GetCollectionParams, context?: ToolContext): Promise<ToolResponse> { try { context?.logger?.info('Executing get_collection tool', { params }); // Validate parameters const validatedParams = this.validateParams(params); // Since the API doesn't have a direct getCollection method, // we'll search for collections with the specific ID const collectionResponse = await this.apiClient.searchCollections({ query: validatedParams.collection_id, page: 1, page_size: 1, }); if (!collectionResponse || collectionResponse.length === 0) { throw new ToolExecutionError( `Collection with ID ${validatedParams.collection_id} not found`, this.name, { collectionId: validatedParams.collection_id } ); } const collection = collectionResponse[0]; const contents = []; // Add formatted collection info const collectionInfo = [ `Collection: ${collection.collection_name}`, `ID: ${collection.collection_id}`, `Description: ${collection.collection_description}`, `Creators: ${collection.creators.join(', ')}`, `Stamps: ${collection.stamp_count}`, `Total Editions: ${collection.total_editions}`, ].join('\n'); contents.push({ type: 'text' as const, text: collectionInfo }); // If stamps are requested, fetch them if (validatedParams.include_stamps) { try { const stampsResponse = await this.apiClient.searchStamps({ collection_id: validatedParams.collection_id, page: validatedParams.stamps_page, page_size: validatedParams.stamps_limit, }); if (stampsResponse && stampsResponse.length > 0) { contents.push({ type: 'text' as const, text: `\n\nStamps in Collection (Page ${validatedParams.stamps_page}):\n`, }); const stampTable = createTable(stampsResponse, [ { key: 'stamp', label: 'ID' }, { key: 'cpid', label: 'CPID' }, { key: 'creator', label: 'Creator', format: (v: unknown) => typeof v === 'string' ? v.substring(0, 12) + '...' : String(v), }, { key: 'supply', label: 'Supply' }, { key: 'floorPrice', label: 'Floor Price', format: (v: unknown) => (v ? `${String(v)} BTC` : 'N/A'), }, ]); contents.push({ type: 'text' as const, text: stampTable }); contents.push({ type: 'text' as const, text: `\nTotal stamps in collection: ${stampsResponse.length}`, }); } } catch (error) { context?.logger?.warn('Failed to fetch stamps for collection', { error }); contents.push({ type: 'text' as const, text: '\n\nNote: Unable to fetch stamps for this collection', }); } } // Add JSON representation contents.push({ type: 'text' as const, text: JSON.stringify(collection, null, 2), }); return multiResponse(...contents); } catch (error) { context?.logger?.error('Error executing get_collection tool', { error }); if (error instanceof ValidationError) { throw error; } if (error instanceof ToolExecutionError) { throw error; } throw new ToolExecutionError('Failed to retrieve collection information', this.name, error); } } }
• src/schemas/collections.ts:58-80 (schema)

  Zod schema defining the input parameters for the get_collection tool, including collection_id (required), and optional flags for including stamps with pagination.
  export const GetCollectionParamsSchema = z.object({ collection_id: z.string().describe('The ID of the collection to retrieve'), include_stamps: z .boolean() .optional() .default(false) .describe('Whether to include stamps in the collection'), stamps_page: z .number() .int() .positive() .optional() .default(1) .describe('Page number for stamps if included'), stamps_limit: z .number() .int() .positive() .max(100) .optional() .default(20) .describe('Number of stamps per page'), });
• src/tools/collections.ts:365-370 (registration)

  Factory function that instantiates the GetCollectionTool (as 'get_collection') with optional API client, used for tool registration.
  export function createCollectionTools(apiClient?: StampchainClient) { return { get_collection: new GetCollectionTool(apiClient), search_collections: new SearchCollectionsTool(apiClient), }; }
• src/tools/index.ts:28-42 (registration)

  Central factory that creates all tool instances including 'get_collection' from createCollectionTools, spreading them into the main tools registry.
  export function createAllTools(apiClient?: StampchainClient): Record<string, ITool> { const client = apiClient || new StampchainClient(); const stamps = createStampTools(client); const collections = createCollectionTools(client); const tokens = createTokenTools(client); const analysis = createStampAnalysisTools(client); return { ...stamps, ...collections, ...tokens, ...analysis, }; }
• src/api/stampchain-client.ts:455-458 (helper)

  API client method to fetch a specific collection by ID, though the tool uses searchCollections instead (noted in tool comments).
  async getCollection(collectionId: string): Promise<CollectionResponse> { const response = await this.client.get<CollectionResponse>(`/collections/${collectionId}`); return response.data; }