@hyperweb/telescope 1.15.1 → 1.17.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -17,7 +17,7 @@ const plugin = (builder, bundler) => {
17
17
  (0, fs_1.mkdirSync)(mcpServerPath, { recursive: true });
18
18
  (0, fs_1.mkdirSync)((0, path_1.join)(mcpServerPath, 'src'), { recursive: true });
19
19
  (0, fs_1.mkdirSync)((0, path_1.join)(mcpServerPath, 'src', 'prompts'), { recursive: true });
20
- (0, fs_1.mkdirSync)((0, path_1.join)(mcpServerPath, 'src', 'telescope-examples'), { recursive: true });
20
+ (0, fs_1.mkdirSync)((0, path_1.join)(mcpServerPath, 'src', `${packageName}-examples`), { recursive: true });
21
21
  // Generate package.json for MCP server
22
22
  const packageJson = generateMcpPackageJson(packageName);
23
23
  (0, fs_1.writeFileSync)((0, path_1.join)(mcpServerPath, 'package.json'), JSON.stringify(packageJson, null, 2));
@@ -83,8 +83,8 @@ async function main() {
83
83
 
84
84
  // Register blockchain function generator tool
85
85
  server.tool(
86
- 'create-blockchain-function',
87
- 'Create custom blockchain functions by referencing telescope examples and generated code',
86
+ 'use-${packageName}',
87
+ 'Analyzes requests and provides step-by-step implementation guidance for custom blockchain functions using telescope examples as reference',
88
88
  {
89
89
  task: z.string().describe('The blockchain task to implement (e.g., "get balance", "check staking rewards", "query validators")').optional(),
90
90
  chainName: z.string().describe('The blockchain name (e.g., cosmos, osmosis, injective)').optional(),
@@ -96,7 +96,7 @@ async function main() {
96
96
  const { task = 'get account balance', chainName = 'cosmos', functionType = 'query', customRequirements } = args;
97
97
 
98
98
  // Read available examples
99
- const examplesPath = resolve(__dirname, 'telescope-examples');
99
+ const examplesPath = resolve(__dirname, '${packageName}-examples');
100
100
  let availableExamples: string[] = [];
101
101
 
102
102
  try {
@@ -135,7 +135,7 @@ async function main() {
135
135
  '## Instructions for Implementation',
136
136
  '',
137
137
  '### Step 1: Review Available Examples',
138
- 'The following example files are available in \`src/telescope-examples/\`:',
138
+ \`The following example files are available in \\\`src/${packageName}-examples/\\\`:\`,
139
139
  '',
140
140
  examplesList,
141
141
  '',
@@ -223,8 +223,8 @@ async function main() {
223
223
  '',
224
224
  '## Additional Resources',
225
225
  '',
226
- '- **Full codebase reference**: \`src/telescope/\` directory contains all generated types and functions',
227
- '- **Configuration examples**: \`src/telescope-examples/config-example.ts\`',
226
+ \`- **Full codebase reference**: \\\`src/${packageName}/\\\` directory contains all generated types and functions\`,
227
+ \`- **Configuration examples**: \\\`src/${packageName}-examples/config-example.ts\\\`\`,
228
228
  '- **Chain registry data**: \`src/prompts/chains.json\`',
229
229
  '- **Usage guidelines**: Use the \`codegen-usage\` and \`agent-guidelines\` prompts for detailed instructions',
230
230
  '',
@@ -235,7 +235,7 @@ async function main() {
235
235
  '3. Test your implementation with proper error handling',
236
236
  '4. Ensure proper TypeScript types are used',
237
237
  '',
238
- 'The examples in \`telescope-examples/\` are production-ready patterns that you can adapt for any blockchain task.'
238
+ \`The examples in \\\`${packageName}-examples/\\\` are production-ready patterns that you can adapt for any blockchain task.\`
239
239
  ].filter(line => line !== '').join('\\n');
240
240
 
241
241
  return {
@@ -343,11 +343,8 @@ main().catch((error) => {
343
343
  });
344
344
  `;
345
345
  (0, fs_1.writeFileSync)((0, path_1.join)(mcpServerPath, 'src', 'index.ts'), indexContent);
346
- // Generate telescope loader utility
347
- const telescopeLoaderCode = generateTelescopeLoader(packageName);
348
- (0, fs_1.writeFileSync)((0, path_1.join)(mcpServerPath, 'src', 'telescope-loader.ts'), telescopeLoaderCode);
349
346
  // Generate TypeScript configuration
350
- const tsConfig = generateTsConfig();
347
+ const tsConfig = generateTsConfig(packageName);
351
348
  (0, fs_1.writeFileSync)((0, path_1.join)(mcpServerPath, 'tsconfig.json'), JSON.stringify(tsConfig, null, 2));
352
349
  // Generate README
353
350
  const readme = generateReadme(packageName);
@@ -362,13 +359,13 @@ main().catch((error) => {
362
359
  exports.plugin = plugin;
363
360
  function generateMcpPackageJson(packageName) {
364
361
  return {
365
- name: `@${packageName}/mcp-server`,
362
+ name: `${packageName}-mcp`,
366
363
  version: "0.1.0",
367
364
  description: `MCP server for ${packageName} blockchain interactions`,
368
365
  main: "dist/index.js",
369
366
  type: "module",
370
367
  bin: {
371
- [`@${packageName}/mcp-server`]: "./dist/index.js"
368
+ [`${packageName}-mcp-server`]: "./dist/index.js"
372
369
  },
373
370
  scripts: {
374
371
  build: "rimraf dist && tsc",
@@ -395,104 +392,7 @@ function generateMcpPackageJson(packageName) {
395
392
  }
396
393
  };
397
394
  }
398
- function generateMcpServerCode(builder, bundler) {
399
- const outputDirName = (0, path_1.basename)(builder.outPath);
400
- const packageName = outputDirName || bundler.bundle.base;
401
- return `#!/usr/bin/env node
402
-
403
- import { readFileSync } from 'node:fs';
404
- import { dirname, resolve } from 'node:path';
405
- import { fileURLToPath } from 'node:url';
406
-
407
- import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
408
- import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
409
- import { z } from 'zod';
410
-
411
- // NOTE: Tool imports are commented out since they are excluded from build
412
- // Uncomment and modify these imports if you want to include tools in your build
413
- /*
414
- import { getBalanceTool } from './tools/getBalance.js';
415
- import { getBalanceReactTool } from './tools/useBalance.js';
416
- */
417
-
418
- // Get package.json version
419
- const __filename = fileURLToPath(import.meta.url);
420
- const __dirname = dirname(__filename);
421
- const packageJson = JSON.parse(readFileSync(resolve(__dirname, '../package.json'), 'utf8'));
422
- const VERSION = packageJson.version;
423
-
424
- async function main() {
425
- const server = new McpServer({
426
- name: '${packageName} MCP Server',
427
- version: VERSION,
428
- });
429
-
430
- // Add prompts for AI agents
431
- server.prompt(
432
- 'codegen-usage',
433
- 'Guide for using telescope generated code',
434
- async () => {
435
- const promptPath = resolve(__dirname, 'prompts/codegen-usage.md');
436
- const content = readFileSync(promptPath, 'utf-8');
437
- return {
438
- messages: [{
439
- role: 'user',
440
- content: {
441
- type: 'text',
442
- text: content
443
- }
444
- }]
445
- };
446
- }
447
- );
448
-
449
- server.prompt(
450
- 'agent-guidelines',
451
- 'Guidelines for MCP agents using ${packageName}',
452
- async () => {
453
- const promptPath = resolve(__dirname, 'prompts/agent-guidelines.md');
454
- const content = readFileSync(promptPath, 'utf-8');
455
- return {
456
- messages: [{
457
- role: 'user',
458
- content: {
459
- type: 'text',
460
- text: content
461
- }
462
- }]
463
- };
464
- }
465
- );
466
-
467
- // NOTE: Tool registrations are commented out since tool functions are not imported
468
- // Uncomment and modify these registrations if you want to include tools in your build
469
- /*
470
- // Register tools
471
- server.tool('get-balance', 'Get account balance for a specific token', {
472
- address: z.string().describe('The account address'),
473
- chainName: z.string().describe('The blockchain name (e.g., cosmos, osmosis)').optional(),
474
- denom: z.string().describe('The token denomination (e.g., uatom, uosmo)').optional()
475
- }, getBalanceTool);
476
-
477
- server.tool('get-balance-react', 'Get balance using React hook pattern', {
478
- address: z.string().describe('The account address'),
479
- chainName: z.string().describe('The blockchain name').optional(),
480
- displayDenom: z.string().describe('The display denomination').optional()
481
- }, getBalanceReactTool);
482
- */
483
-
484
- const transport = new StdioServerTransport();
485
- await server.connect(transport);
486
- console.log('${packageName} MCP server started on stdio');
487
- }
488
-
489
- main().catch((error) => {
490
- console.error('Fatal error in main()', error);
491
- process.exit(1);
492
- });
493
- `;
494
- }
495
- function generateTsConfig() {
395
+ function generateTsConfig(packageName) {
496
396
  return {
497
397
  compilerOptions: {
498
398
  target: "ES2022",
@@ -511,15 +411,13 @@ function generateTsConfig() {
511
411
  resolveJsonModule: true
512
412
  },
513
413
  include: ["src/**/*"],
514
- exclude: ["node_modules", "dist", "src/telescope/**/*", "src/telescope-examples/**/*"]
414
+ exclude: ["node_modules", "dist", `src/${packageName}/**/*`, `src/${packageName}-examples/**/*`]
515
415
  };
516
416
  }
517
417
  function generateReadme(packageName) {
518
418
  return `# ${packageName.charAt(0).toUpperCase() + packageName.slice(1)} MCP Server
519
419
 
520
- This MCP server provides AI agents with tools to interact with blockchain through generated TypeScript clients.
521
-
522
- **Note**: This MCP server contains a complete copy of the telescope generated codebase in \`src/telescope/\` for AI agents to reference, but uses mock implementations for demonstration. The telescope code is excluded from the build process.
420
+ This MCP server provides AI agents with the \`use-${packageName}\` tool to create custom blockchain functions using telescope examples as reference.
523
421
 
524
422
  ## Installation
525
423
 
@@ -548,12 +446,19 @@ Add this configuration to your AI agent's MCP settings:
548
446
 
549
447
  This MCP server provides:
550
448
 
551
- - **Comprehensive Examples**: Reference implementations in \`src/telescope-examples/\`
552
- - **Function Generator Tool**: AI-powered tool that creates custom blockchain functions based on user requirements
553
- - **AI Guidance**: Prompt files to help AI agents understand blockchain development
554
- - **Complete Codebase**: Full telescope-generated code in \`src/telescope/\` for reference
449
+ - **Function Generator Tool**: Single tool (\`use-${packageName}\`) that analyzes requests and provides step-by-step implementation guidance
450
+ - **Telescope Codebase Reference**: Complete telescope-generated code in \`src/${packageName}/\` as primary reference
451
+ - **Production Examples**: Reference implementations in \`src/${packageName}-examples/\` showing real-world patterns
452
+ - **AI Guidance**: Contextual prompts to help agents understand blockchain development patterns
453
+
454
+ ## How It Works
555
455
 
556
- **Note**: The MCP server uses a meta-tool approach - instead of predefined tools, it instructs agents to create custom functions by referencing the comprehensive examples.
456
+ The function generator tool:
457
+
458
+ 1. **Analyzes your request** (task, chain, function type, custom requirements)
459
+ 2. **Finds relevant examples** from \`${packageName}-examples/\` directory
460
+ 3. **Provides implementation patterns** using \`${packageName}/\` codebase as primary reference
461
+ 4. **Shows proper imports** and configuration with error handling
557
462
 
558
463
  ## Development
559
464
 
@@ -563,12 +468,16 @@ npm run inspector # Run MCP inspector for testing
563
468
  npm run clean # Clean dist directory
564
469
  \`\`\`
565
470
 
566
- ## Directory Structure
471
+ ## Extending Examples
472
+
473
+ You can enhance the AI agent's knowledge by adding more examples to the \`${packageName}-examples/\` directory. The function generator automatically scans this directory, so new examples are immediately available for reference.
474
+
475
+ ## Directory Structure
567
476
 
568
477
  \`\`\`
569
478
  ${packageName}-mcp/
570
479
  ├── src/
571
- │ ├── telescope/ # 📚 Telescope generated code (reference only, excluded from build)
480
+ │ ├── ${packageName}/ # 📚 Telescope generated code (primary reference, excluded from build)
572
481
  │ │ ├── cosmos/ # Full cosmos SDK modules
573
482
  │ │ │ ├── bank/ # Balance queries, transfers
574
483
  │ │ │ ├── staking/ # Validator operations
@@ -576,7 +485,7 @@ ${packageName}-mcp/
576
485
  │ │ ├── osmosis/ # Osmosis DEX functionality
577
486
  │ │ ├── ibc/ # Inter-blockchain communication
578
487
  │ │ └── index.ts # Main exports
579
- │ ├── telescope-examples/ # 📖 Usage examples and patterns (excluded from build)
488
+ │ ├── ${packageName}-examples/ # 📖 Production examples (excluded from build)
580
489
  │ │ ├── config-example.ts # Chain configuration setup
581
490
  │ │ ├── useBalance.ts # Balance query React hooks
582
491
  │ │ ├── useBalanceFunc.ts # Direct balance functions
@@ -590,23 +499,26 @@ ${packageName}-mcp/
590
499
  │ │ ├── useGrants.ts # Authorization grants
591
500
  │ │ └── useSendData.ts # Transaction preparation
592
501
  │ ├── prompts/ # 🤖 Agent instruction files
593
- │ │ ├── codegen-usage.md # Telescope usage guide
502
+ │ │ ├── codegen-usage.md # Implementation guide for agents
594
503
  │ │ ├── agent-guidelines.md # Best practices for agents
595
504
  │ │ └── chains.json # Chain registry data
596
- ├── index.ts # MCP server with function generator tool
597
- │ └── telescope-loader.ts # Utility for dynamic code loading
598
- ├── dist/ # Compiled JavaScript (excludes telescope/ and telescope-examples/)
505
+ └── index.ts # MCP server with function generator tool
506
+ ├── dist/ # Compiled JavaScript (excludes ${packageName}/ and ${packageName}-examples/)
599
507
  └── package.json
600
508
  \`\`\`
601
509
 
602
- The \`src/telescope/\` and \`src/telescope-examples/\` directories contain reference code for AI agents but are excluded from the TypeScript build process.
510
+ **Key Points:**
511
+ - \`src/${packageName}/\` contains the complete telescope-generated codebase as the **primary reference**
512
+ - \`src/${packageName}-examples/\` contains **production examples** for patterns and logic reference
513
+ - Both directories are excluded from TypeScript build but available for AI agents to read
514
+ - Examples may contain compilation errors - focus on logic and patterns, not direct copying
603
515
 
604
516
  Generated by [Telescope](https://github.com/hyperweb-io/telescope) 🔭
605
517
  `;
606
518
  }
607
519
  function copyTelescopeCodebase(builder, mcpServerPath, packageName) {
608
520
  const sourcePath = builder.outPath;
609
- const destPath = (0, path_1.join)(mcpServerPath, 'src', 'telescope');
521
+ const destPath = (0, path_1.join)(mcpServerPath, 'src', packageName);
610
522
  // Copy the entire telescope generated directory
611
523
  if ((0, fs_1.existsSync)(sourcePath)) {
612
524
  // Skip copy if destination already exists (avoids Windows file permission issues)
@@ -632,180 +544,143 @@ function copyTelescopeCodebase(builder, mcpServerPath, packageName) {
632
544
  }
633
545
  }
634
546
  // Removed retry logic - no longer needed since we skip copy if destination exists
635
- function generateTelescopeLoader(packageName) {
636
- return `import { readFileSync } from 'node:fs';
637
- import { resolve, dirname } from 'node:path';
638
- import { fileURLToPath } from 'node:url';
547
+ function generateComprehensivePrompts(mcpServerPath, packageName) {
548
+ // Generate codegen-usage.md with our updated content
549
+ const codegenUsageContent = `# Codegen Usage Guide
639
550
 
640
- const __filename = fileURLToPath(import.meta.url);
641
- const __dirname = dirname(__filename);
551
+ ## Overview
552
+ This guide provides instructions for MCP agents on how to use the telescope generated code when implementing the \`use-${packageName}\` tool.
642
553
 
643
- /**
644
- * Load telescope generated modules dynamically
645
- * This utility helps MCP tools access the telescope codebase
646
- */
647
- export class TelescopeLoader {
648
- private basePath: string;
554
+ ## Understanding the Structure
649
555
 
650
- constructor() {
651
- this.basePath = resolve(__dirname, 'telescope');
652
- }
556
+ ### Primary Reference: \`src/${packageName}/\` Directory
557
+ This is your **main reference** for understanding the complete telescope-generated codebase. It contains:
653
558
 
654
- /**
655
- * Get available modules in the telescope codebase
656
- */
657
- getAvailableModules(): string[] {
658
- // This would typically read the directory structure
659
- // For now, return common cosmos modules
660
- return [
661
- 'cosmos/bank/v1beta1',
662
- 'cosmos/staking/v1beta1',
663
- 'cosmos/gov/v1beta1',
664
- 'cosmos/distribution/v1beta1',
665
- 'cosmwasm/wasm/v1',
666
- 'ibc/core/client/v1',
667
- 'osmosis/gamm/v1beta1'
668
- ];
669
- }
559
+ - **Complete type definitions** for all blockchain modules
560
+ - **Client implementations** for queries and transactions
561
+ - **Generated interfaces** from protobuf definitions
562
+ - **All available methods** and their signatures
670
563
 
671
- /**
672
- * Load module documentation/examples
673
- */
674
- loadModuleInfo(modulePath: string) {
675
- try {
676
- const infoPath = resolve(this.basePath, modulePath, 'README.md');
677
- return readFileSync(infoPath, 'utf-8');
678
- } catch (error) {
679
- return \`Module documentation not found for \${modulePath}\`;
680
- }
681
- }
564
+ **Key files to understand**:
565
+ - \`src/${packageName}/index.ts\` - Main exports and available modules
566
+ - \`src/${packageName}/cosmos/\` - Cosmos SDK modules (bank, staking, gov, etc.)
567
+ - \`src/${packageName}/osmosis/\` - Osmosis-specific modules
568
+ - \`src/${packageName}/ibc/\` - Inter-blockchain communication
569
+ - \`src/${packageName}/README.md\` - Comprehensive documentation
682
570
 
683
- /**
684
- * Get module schema information
685
- */
686
- getModuleSchema(modulePath: string) {
687
- // Return basic schema info for the module
688
- return {
689
- module: modulePath,
690
- package: '${packageName}',
691
- queries: ['getBalance', 'getAllBalances'],
692
- mutations: ['send', 'delegate'],
693
- types: ['Coin', 'MsgSend', 'MsgDelegate']
694
- };
695
- }
696
- }
697
-
698
- export const telescopeLoader = new TelescopeLoader();
699
- `;
700
- }
701
- function generateComprehensivePrompts(mcpServerPath, packageName) {
702
- // Generate codegen-usage.md
703
- const codegenUsageContent = `# Codegen Usage Guide
571
+ ### Production Examples: \`src/${packageName}-examples/\` Directory
572
+ Use these as **implementation patterns** and **logic reference**:
704
573
 
705
- ## Overview
706
- This guide provides instructions for MCP agents on how to use the telescope generated code in the ${packageName} package.
574
+ - **Real production code** showing how to use telescope functions
575
+ - **Best practices** for error handling and data processing
576
+ - **Complete workflows** for common blockchain operations
707
577
 
708
- ## Category of Functions
578
+ **⚠️ Important**: These examples may contain import/compilation errors since they reference the main codebase. **Focus on the logic and patterns** rather than copying code directly.
709
579
 
710
- ### 1. **.rpc.func** - Direct Function Calls
711
- These are direct async functions that make RPC calls to blockchain nodes. Use these for:
712
- - Server-side operations
713
- - Node.js scripts
714
- - Direct blockchain queries outside React
580
+ ## Using the MCP Tool
715
581
 
716
- **Import Pattern**:
717
- \`\`\`typescript
718
- import { getBalance } from '${packageName}/cosmos/bank/v1beta1/query.rpc.func';
719
- import { send } from '${packageName}/cosmos/bank/v1beta1/tx.rpc.func';
720
- \`\`\`
582
+ ### Single Tool: \`use-${packageName}\`
583
+ This MCP server provides one tool that generates implementation guidance by:
721
584
 
722
- **Usage Examples**:
585
+ 1. **Analyzing your request** (task, chain, function type)
586
+ 2. **Finding relevant examples** from \`${packageName}-examples/\`
587
+ 3. **Providing step-by-step guidance** using telescope patterns
588
+ 4. **Showing proper imports** and configuration
723
589
 
724
- **Query Balance**:
725
- \`\`\`typescript
726
- import { getBalance } from '${packageName}/cosmos/bank/v1beta1/query.rpc.func';
590
+ ## Implementation Approach
727
591
 
728
- // Basic balance query
729
- const { balance } = await getBalance(rpcEndpoint, {
730
- address: "cosmos1...",
731
- denom: "uatom"
732
- });
592
+ ### Step 1: Understand Telescope Structure
593
+ When implementing a function, first explore \`src/${packageName}/\` to understand:
733
594
 
734
- // With error handling
735
- try {
736
- const { balance } = await getBalance(rpcEndpoint, { address, denom });
737
- const atomAmount = Number(balance?.amount || 0) / Math.pow(10, 6); // Convert uatom to ATOM
738
- return atomAmount;
739
- } catch (error) {
740
- console.error('Error fetching balance:', error);
741
- return null;
742
- }
595
+ \`\`\`typescript
596
+ // Example: For balance queries, look at:
597
+ // src/${packageName}/cosmos/bank/v1beta1/query.ts - Type definitions
598
+ // src/${packageName}/cosmos/bank/v1beta1/query.rpc.Query.ts - Query client
599
+ // src/${packageName}/cosmos/bank/v1beta1/query.rpc.func.ts - Direct functions
600
+ // src/${packageName}/cosmos/bank/v1beta1/query.rpc.react.ts - React hooks
743
601
  \`\`\`
744
602
 
745
- ### 2. **.rpc.react** - React Hooks
746
- These are React hooks for frontend applications. They provide:
747
- - Automatic caching and refetching
748
- - Loading states
749
- - Error handling
750
- - Integration with React Query
603
+ ### Step 2: Reference Production Examples
604
+ Look at \`${packageName}-examples/\` for implementation patterns:
751
605
 
752
- **Import Pattern**:
753
606
  \`\`\`typescript
754
- import { useGetBalance } from '${packageName}/cosmos/bank/v1beta1/query.rpc.react';
755
- import { useSend } from '${packageName}/cosmos/bank/v1beta1/tx.rpc.react';
607
+ // Example: useBalance.ts shows the pattern for:
608
+ // - Proper imports from telescope
609
+ // - Error handling approaches
610
+ // - Data transformation logic
611
+ // - Integration with React Query
612
+
613
+ // Focus on UNDERSTANDING the logic:
614
+ // - How RPC endpoints are configured
615
+ // - How parameters are validated
616
+ // - How responses are processed
617
+ // - How errors are handled
756
618
  \`\`\`
757
619
 
758
- ## Chain Configuration Setup
620
+ ### Step 3: Generate Your Implementation
621
+ Use the patterns from both directories to create your function:
759
622
 
760
- ### Import Chain Registry Data
761
623
  \`\`\`typescript
762
- import { assetLists, chains } from "@chain-registry/v2";
624
+ // Your implementation should:
625
+ // 1. Use proper imports from the telescope codebase
626
+ // 2. Follow error handling patterns from examples
627
+ // 3. Include proper TypeScript types
628
+ // 4. Handle edge cases shown in examples
763
629
  \`\`\`
764
630
 
765
- ### Basic Configuration
766
- \`\`\`typescript
767
- // Define your target chain
768
- export const defaultChainName = 'cosmos'; // or 'osmosis', 'injective', etc.
769
-
770
- // Find chain info from registry
771
- export const defaultChain = chains.find((chain) => chain.chainName === defaultChainName);
631
+ ## Category of Functions in Telescope
772
632
 
773
- // Get RPC endpoint
774
- export const defaultRpcEndpoint = defaultChain?.apis?.rpc?.[0]?.address || 'http://localhost:26657';
775
- \`\`\`
776
-
777
- ## Detailed Examples Reference
633
+ ### 1. **query.rpc.func.ts** - Direct Function Calls
634
+ - Server-side operations
635
+ - Node.js scripts
636
+ - Direct blockchain queries
778
637
 
779
- ### Using src/telescope-examples Directory
780
- When you need more specific implementation details or complex use cases, reference the example files in \`src/telescope-examples/\`. These are real-world examples for production usage.
638
+ ### 2. **query.rpc.react.ts** - React Hooks
639
+ - Frontend applications
640
+ - Automatic caching and refetching
641
+ - Loading states and error handling
781
642
 
782
- ### Using src/tools Directory
783
- The \`src/tools/\` directory contains MCP tool implementations that demonstrate how to use the telescope-examples in MCP tools. These tools show patterns for:
784
- - Importing functions from telescope-examples
785
- - Handling errors and returning proper MCP responses
786
- - Working with blockchain data in MCP context
643
+ ### 3. **tx.rpc.func.ts** - Transaction Functions
644
+ - Broadcasting transactions
645
+ - Message composition
787
646
 
788
- Each tool in \`src/tools/\` corresponds to functionality in \`src/telescope-examples/\` and shows how to bridge the gap between React hooks/utility functions and MCP tool implementations.
647
+ ### 4. **tx.rpc.react.ts** - Transaction Hooks
648
+ - Transaction broadcasting in React
649
+ - Transaction state management
789
650
 
790
- ## Important Notes
651
+ ## Chain Configuration Pattern
791
652
 
792
- ### Function Categories Usage
793
- - **Use .rpc.func** for: Server-side scripts, CLI tools, backend services
794
- - **Use .rpc.react** for: React applications, frontend components with state management
653
+ Always reference \`config-example.ts\` for proper setup:
795
654
 
796
- ### Error Handling Patterns
797
655
  \`\`\`typescript
798
- // For .rpc.func
799
- try {
800
- const result = await getBalance(rpcEndpoint, { address, denom });
801
- return result;
802
- } catch (error) {
803
- if (error.message.includes('not found')) {
804
- return null; // Handle account not found
805
- }
806
- throw error; // Re-throw other errors
807
- }
656
+ import { assetLists, chains } from "@chain-registry/v2";
657
+
658
+ export const targetChainName = 'cosmos';
659
+ export const rpcEndpoint = 'https://cosmos-rpc.quickapi.com:443';
660
+ export const chain = chains.find((chain) => chain.chainName === targetChainName);
661
+ export const assetList = assetLists.find((assetList) => assetList.chainName === targetChainName);
808
662
  \`\`\`
663
+
664
+ ## Important Guidelines
665
+
666
+ ### When Using Examples
667
+ - **Study the logic**, don't copy/paste directly
668
+ - **Understand the patterns** for imports and usage
669
+ - **Learn from error handling** approaches
670
+ - **Adapt the structure** to your specific needs
671
+
672
+ ### When Using Telescope Codebase
673
+ - **Browse the generated files** to understand available methods
674
+ - **Check type definitions** for proper parameter structures
675
+ - **Look at client implementations** for usage patterns
676
+ - **Reference documentation** in README.md files
677
+
678
+ ### Best Practices
679
+ 1. Always include comprehensive error handling
680
+ 2. Validate input parameters before making calls
681
+ 3. Convert base units to human-readable amounts when needed
682
+ 4. Use proper TypeScript types from telescope
683
+ 5. Test your implementations thoroughly
809
684
  `;
810
685
  (0, fs_1.writeFileSync)((0, path_1.join)(mcpServerPath, 'src', 'prompts', 'codegen-usage.md'), codegenUsageContent);
811
686
  // Generate agent-guidelines.md
@@ -967,17 +842,16 @@ function generateTelescopeExamples(mcpServerPath, packageName) {
967
842
  content: `import { assetLists, chains } from "@chain-registry/v2";
968
843
 
969
844
  /**
845
+ * Chain configuration example
970
846
  * mainnet: 'cosmos'
971
- * testnet: 'cosmoshub-testnet'
847
+ * testnet: 'cosmoshub-testnet'
972
848
  * mainnet rpc: 'https://cosmos-rpc.quickapi.com:443'
973
849
  * testnet rpc: 'https://rpc.testnet.cosmos.network:443'
974
850
  */
975
- export const defaultChainName = 'cosmos'
976
- export const defaultRpcEndpoint = 'https://cosmos-rpc.quickapi.com:443'
977
-
978
- export const defaultChain = chains.find((chain) => chain.chainName === defaultChainName)
979
-
980
- export const defaultAssetList = assetLists.find((assetList) => assetList.chainName === defaultChainName)
851
+ export const targetChainName = 'cosmos';
852
+ export const rpcEndpoint = 'https://cosmos-rpc.quickapi.com:443';
853
+ export const chain = chains.find((chain) => chain.chainName === targetChainName);
854
+ export const assetList = assetLists.find((assetList) => assetList.chainName === targetChainName);
981
855
  `
982
856
  },
983
857
  {
@@ -1848,6 +1722,6 @@ export const useTotalAssets = (chainName: string) => {
1848
1722
  ];
1849
1723
  // Write all example files
1850
1724
  exampleFiles.forEach(({ name, content }) => {
1851
- (0, fs_1.writeFileSync)((0, path_1.join)(mcpServerPath, 'src', 'telescope-examples', name), content);
1725
+ (0, fs_1.writeFileSync)((0, path_1.join)(mcpServerPath, 'src', `${packageName}-examples`, name), content);
1852
1726
  });
1853
1727
  }
@@ -114,7 +114,7 @@ function getTypesForPackage(builder, packageName) {
114
114
  return uniqueTypes.sort((a, b) => a.name.localeCompare(b.name));
115
115
  }
116
116
  const plugin = (builder) => {
117
- if (!builder.options.readme.enabled && !builder.options.mcpServer.enabled) {
117
+ if (!builder.options?.readme?.enabled && !builder.options?.mcpServer?.enabled) {
118
118
  return;
119
119
  }
120
120
  const readmePath = (0, path_1.join)(builder.outPath, "README.md");