@hyperweb/telescope 1.15.2 → 1.17.1
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.
- package/README.md +5 -5
- package/main/generators/create-combined-stargate-clients.js +99 -0
- package/main/generators/create-helpers.js +15 -8
- package/main/generators/create-mcp-server.js +153 -279
- package/main/generators/create-root-readme.js +1 -1
- package/main/helpers/external-icjs.js +29 -19
- package/main/helpers/generated-type.js +24 -0
- package/main/helpers/helper-func-types-interface.js +8 -8
- package/main/helpers/helper-func-types.js +8 -8
- package/main/helpers/internalForBigInt.js +248 -0
- package/main/helpers/types.js +24 -0
- package/main/helpers/vue-query.js +91 -0
- package/main/protod/proto-download.js +57 -0
- package/module/generators/create-combined-stargate-clients.js +95 -0
- package/module/generators/create-helpers.js +15 -8
- package/module/generators/create-mcp-server.js +153 -279
- package/module/generators/create-root-readme.js +1 -1
- package/module/helpers/external-icjs.js +29 -19
- package/module/helpers/generated-type.js +21 -0
- package/module/helpers/helper-func-types-interface.js +8 -8
- package/module/helpers/helper-func-types.js +8 -8
- package/module/helpers/internalForBigInt.js +245 -0
- package/module/helpers/types.js +21 -0
- package/module/helpers/vue-query.js +87 -0
- package/module/protod/proto-download.js +55 -0
- package/module/telescope.js +0 -0
- package/package.json +6 -6
- package/src/generators/create-helpers.ts +29 -16
- package/src/generators/create-mcp-server.ts +154 -282
- package/src/generators/create-root-readme.ts +1 -1
- package/src/helpers/external-icjs.ts +29 -19
- package/src/helpers/helper-func-types-interface.ts +8 -8
- package/src/helpers/helper-func-types.ts +8 -8
- package/types/codegen/cosmos/orm/module/v1alpha1/module.d.ts +43 -0
- package/types/helpers/external-icjs.d.ts +1 -1
|
@@ -22,7 +22,7 @@ export const plugin = (
|
|
|
22
22
|
mkdirSync(mcpServerPath, { recursive: true });
|
|
23
23
|
mkdirSync(join(mcpServerPath, 'src'), { recursive: true });
|
|
24
24
|
mkdirSync(join(mcpServerPath, 'src', 'prompts'), { recursive: true });
|
|
25
|
-
mkdirSync(join(mcpServerPath, 'src',
|
|
25
|
+
mkdirSync(join(mcpServerPath, 'src', `${packageName}-examples`), { recursive: true });
|
|
26
26
|
|
|
27
27
|
// Generate package.json for MCP server
|
|
28
28
|
const packageJson = generateMcpPackageJson(packageName);
|
|
@@ -93,8 +93,8 @@ async function main() {
|
|
|
93
93
|
|
|
94
94
|
// Register blockchain function generator tool
|
|
95
95
|
server.tool(
|
|
96
|
-
'
|
|
97
|
-
'
|
|
96
|
+
'use-${packageName}',
|
|
97
|
+
'Analyzes requests and provides step-by-step implementation guidance for custom blockchain functions using telescope examples as reference',
|
|
98
98
|
{
|
|
99
99
|
task: z.string().describe('The blockchain task to implement (e.g., "get balance", "check staking rewards", "query validators")').optional(),
|
|
100
100
|
chainName: z.string().describe('The blockchain name (e.g., cosmos, osmosis, injective)').optional(),
|
|
@@ -106,7 +106,7 @@ async function main() {
|
|
|
106
106
|
const { task = 'get account balance', chainName = 'cosmos', functionType = 'query', customRequirements } = args;
|
|
107
107
|
|
|
108
108
|
// Read available examples
|
|
109
|
-
const examplesPath = resolve(__dirname, '
|
|
109
|
+
const examplesPath = resolve(__dirname, '${packageName}-examples');
|
|
110
110
|
let availableExamples: string[] = [];
|
|
111
111
|
|
|
112
112
|
try {
|
|
@@ -145,7 +145,7 @@ async function main() {
|
|
|
145
145
|
'## Instructions for Implementation',
|
|
146
146
|
'',
|
|
147
147
|
'### Step 1: Review Available Examples',
|
|
148
|
-
|
|
148
|
+
\`The following example files are available in \\\`src/${packageName}-examples/\\\`:\`,
|
|
149
149
|
'',
|
|
150
150
|
examplesList,
|
|
151
151
|
'',
|
|
@@ -233,8 +233,8 @@ async function main() {
|
|
|
233
233
|
'',
|
|
234
234
|
'## Additional Resources',
|
|
235
235
|
'',
|
|
236
|
-
|
|
237
|
-
|
|
236
|
+
\`- **Full codebase reference**: \\\`src/${packageName}/\\\` directory contains all generated types and functions\`,
|
|
237
|
+
\`- **Configuration examples**: \\\`src/${packageName}-examples/config-example.ts\\\`\`,
|
|
238
238
|
'- **Chain registry data**: \`src/prompts/chains.json\`',
|
|
239
239
|
'- **Usage guidelines**: Use the \`codegen-usage\` and \`agent-guidelines\` prompts for detailed instructions',
|
|
240
240
|
'',
|
|
@@ -245,7 +245,7 @@ async function main() {
|
|
|
245
245
|
'3. Test your implementation with proper error handling',
|
|
246
246
|
'4. Ensure proper TypeScript types are used',
|
|
247
247
|
'',
|
|
248
|
-
|
|
248
|
+
\`The examples in \\\`${packageName}-examples/\\\` are production-ready patterns that you can adapt for any blockchain task.\`
|
|
249
249
|
].filter(line => line !== '').join('\\n');
|
|
250
250
|
|
|
251
251
|
return {
|
|
@@ -358,15 +358,10 @@ main().catch((error) => {
|
|
|
358
358
|
indexContent
|
|
359
359
|
);
|
|
360
360
|
|
|
361
|
-
|
|
362
|
-
const telescopeLoaderCode = generateTelescopeLoader(packageName);
|
|
363
|
-
writeFileSync(
|
|
364
|
-
join(mcpServerPath, 'src', 'telescope-loader.ts'),
|
|
365
|
-
telescopeLoaderCode
|
|
366
|
-
);
|
|
361
|
+
|
|
367
362
|
|
|
368
363
|
// Generate TypeScript configuration
|
|
369
|
-
const tsConfig = generateTsConfig();
|
|
364
|
+
const tsConfig = generateTsConfig(packageName);
|
|
370
365
|
writeFileSync(
|
|
371
366
|
join(mcpServerPath, 'tsconfig.json'),
|
|
372
367
|
JSON.stringify(tsConfig, null, 2)
|
|
@@ -392,13 +387,13 @@ main().catch((error) => {
|
|
|
392
387
|
function generateMcpPackageJson(packageName: string) {
|
|
393
388
|
|
|
394
389
|
return {
|
|
395
|
-
name:
|
|
390
|
+
name: `${packageName}-mcp`,
|
|
396
391
|
version: "0.1.0",
|
|
397
392
|
description: `MCP server for ${packageName} blockchain interactions`,
|
|
398
393
|
main: "dist/index.js",
|
|
399
394
|
type: "module",
|
|
400
395
|
bin: {
|
|
401
|
-
[
|
|
396
|
+
[`${packageName}-mcp-server`]: "./dist/index.js"
|
|
402
397
|
},
|
|
403
398
|
scripts: {
|
|
404
399
|
build: "rimraf dist && tsc",
|
|
@@ -426,106 +421,8 @@ function generateMcpPackageJson(packageName: string) {
|
|
|
426
421
|
};
|
|
427
422
|
}
|
|
428
423
|
|
|
429
|
-
function generateMcpServerCode(builder: TelescopeBuilder, bundler: Bundler) {
|
|
430
|
-
const outputDirName = basename(builder.outPath);
|
|
431
|
-
const packageName = outputDirName || bundler.bundle.base;
|
|
432
424
|
|
|
433
|
-
|
|
434
|
-
|
|
435
|
-
import { readFileSync } from 'node:fs';
|
|
436
|
-
import { dirname, resolve } from 'node:path';
|
|
437
|
-
import { fileURLToPath } from 'node:url';
|
|
438
|
-
|
|
439
|
-
import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
|
|
440
|
-
import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
|
|
441
|
-
import { z } from 'zod';
|
|
442
|
-
|
|
443
|
-
// NOTE: Tool imports are commented out since they are excluded from build
|
|
444
|
-
// Uncomment and modify these imports if you want to include tools in your build
|
|
445
|
-
/*
|
|
446
|
-
import { getBalanceTool } from './tools/getBalance.js';
|
|
447
|
-
import { getBalanceReactTool } from './tools/useBalance.js';
|
|
448
|
-
*/
|
|
449
|
-
|
|
450
|
-
// Get package.json version
|
|
451
|
-
const __filename = fileURLToPath(import.meta.url);
|
|
452
|
-
const __dirname = dirname(__filename);
|
|
453
|
-
const packageJson = JSON.parse(readFileSync(resolve(__dirname, '../package.json'), 'utf8'));
|
|
454
|
-
const VERSION = packageJson.version;
|
|
455
|
-
|
|
456
|
-
async function main() {
|
|
457
|
-
const server = new McpServer({
|
|
458
|
-
name: '${packageName} MCP Server',
|
|
459
|
-
version: VERSION,
|
|
460
|
-
});
|
|
461
|
-
|
|
462
|
-
// Add prompts for AI agents
|
|
463
|
-
server.prompt(
|
|
464
|
-
'codegen-usage',
|
|
465
|
-
'Guide for using telescope generated code',
|
|
466
|
-
async () => {
|
|
467
|
-
const promptPath = resolve(__dirname, 'prompts/codegen-usage.md');
|
|
468
|
-
const content = readFileSync(promptPath, 'utf-8');
|
|
469
|
-
return {
|
|
470
|
-
messages: [{
|
|
471
|
-
role: 'user',
|
|
472
|
-
content: {
|
|
473
|
-
type: 'text',
|
|
474
|
-
text: content
|
|
475
|
-
}
|
|
476
|
-
}]
|
|
477
|
-
};
|
|
478
|
-
}
|
|
479
|
-
);
|
|
480
|
-
|
|
481
|
-
server.prompt(
|
|
482
|
-
'agent-guidelines',
|
|
483
|
-
'Guidelines for MCP agents using ${packageName}',
|
|
484
|
-
async () => {
|
|
485
|
-
const promptPath = resolve(__dirname, 'prompts/agent-guidelines.md');
|
|
486
|
-
const content = readFileSync(promptPath, 'utf-8');
|
|
487
|
-
return {
|
|
488
|
-
messages: [{
|
|
489
|
-
role: 'user',
|
|
490
|
-
content: {
|
|
491
|
-
type: 'text',
|
|
492
|
-
text: content
|
|
493
|
-
}
|
|
494
|
-
}]
|
|
495
|
-
};
|
|
496
|
-
}
|
|
497
|
-
);
|
|
498
|
-
|
|
499
|
-
// NOTE: Tool registrations are commented out since tool functions are not imported
|
|
500
|
-
// Uncomment and modify these registrations if you want to include tools in your build
|
|
501
|
-
/*
|
|
502
|
-
// Register tools
|
|
503
|
-
server.tool('get-balance', 'Get account balance for a specific token', {
|
|
504
|
-
address: z.string().describe('The account address'),
|
|
505
|
-
chainName: z.string().describe('The blockchain name (e.g., cosmos, osmosis)').optional(),
|
|
506
|
-
denom: z.string().describe('The token denomination (e.g., uatom, uosmo)').optional()
|
|
507
|
-
}, getBalanceTool);
|
|
508
|
-
|
|
509
|
-
server.tool('get-balance-react', 'Get balance using React hook pattern', {
|
|
510
|
-
address: z.string().describe('The account address'),
|
|
511
|
-
chainName: z.string().describe('The blockchain name').optional(),
|
|
512
|
-
displayDenom: z.string().describe('The display denomination').optional()
|
|
513
|
-
}, getBalanceReactTool);
|
|
514
|
-
*/
|
|
515
|
-
|
|
516
|
-
const transport = new StdioServerTransport();
|
|
517
|
-
await server.connect(transport);
|
|
518
|
-
console.log('${packageName} MCP server started on stdio');
|
|
519
|
-
}
|
|
520
|
-
|
|
521
|
-
main().catch((error) => {
|
|
522
|
-
console.error('Fatal error in main()', error);
|
|
523
|
-
process.exit(1);
|
|
524
|
-
});
|
|
525
|
-
`;
|
|
526
|
-
}
|
|
527
|
-
|
|
528
|
-
function generateTsConfig() {
|
|
425
|
+
function generateTsConfig(packageName: string) {
|
|
529
426
|
return {
|
|
530
427
|
compilerOptions: {
|
|
531
428
|
target: "ES2022",
|
|
@@ -544,7 +441,7 @@ function generateTsConfig() {
|
|
|
544
441
|
resolveJsonModule: true
|
|
545
442
|
},
|
|
546
443
|
include: ["src/**/*"],
|
|
547
|
-
exclude: ["node_modules", "dist",
|
|
444
|
+
exclude: ["node_modules", "dist", `src/${packageName}/**/*`, `src/${packageName}-examples/**/*`]
|
|
548
445
|
};
|
|
549
446
|
}
|
|
550
447
|
|
|
@@ -552,9 +449,7 @@ function generateReadme(packageName: string) {
|
|
|
552
449
|
|
|
553
450
|
return `# ${packageName.charAt(0).toUpperCase() + packageName.slice(1)} MCP Server
|
|
554
451
|
|
|
555
|
-
This MCP server provides AI agents with
|
|
556
|
-
|
|
557
|
-
**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.
|
|
452
|
+
This MCP server provides AI agents with the \`use-${packageName}\` tool to create custom blockchain functions using telescope examples as reference.
|
|
558
453
|
|
|
559
454
|
## Installation
|
|
560
455
|
|
|
@@ -583,12 +478,19 @@ Add this configuration to your AI agent's MCP settings:
|
|
|
583
478
|
|
|
584
479
|
This MCP server provides:
|
|
585
480
|
|
|
586
|
-
- **
|
|
587
|
-
- **
|
|
588
|
-
- **
|
|
589
|
-
- **
|
|
481
|
+
- **Function Generator Tool**: Single tool (\`use-${packageName}\`) that analyzes requests and provides step-by-step implementation guidance
|
|
482
|
+
- **Telescope Codebase Reference**: Complete telescope-generated code in \`src/${packageName}/\` as primary reference
|
|
483
|
+
- **Production Examples**: Reference implementations in \`src/${packageName}-examples/\` showing real-world patterns
|
|
484
|
+
- **AI Guidance**: Contextual prompts to help agents understand blockchain development patterns
|
|
485
|
+
|
|
486
|
+
## How It Works
|
|
590
487
|
|
|
591
|
-
|
|
488
|
+
The function generator tool:
|
|
489
|
+
|
|
490
|
+
1. **Analyzes your request** (task, chain, function type, custom requirements)
|
|
491
|
+
2. **Finds relevant examples** from \`${packageName}-examples/\` directory
|
|
492
|
+
3. **Provides implementation patterns** using \`${packageName}/\` codebase as primary reference
|
|
493
|
+
4. **Shows proper imports** and configuration with error handling
|
|
592
494
|
|
|
593
495
|
## Development
|
|
594
496
|
|
|
@@ -598,12 +500,16 @@ npm run inspector # Run MCP inspector for testing
|
|
|
598
500
|
npm run clean # Clean dist directory
|
|
599
501
|
\`\`\`
|
|
600
502
|
|
|
601
|
-
|
|
503
|
+
## Extending Examples
|
|
504
|
+
|
|
505
|
+
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.
|
|
506
|
+
|
|
507
|
+
## Directory Structure
|
|
602
508
|
|
|
603
509
|
\`\`\`
|
|
604
510
|
${packageName}-mcp/
|
|
605
511
|
├── src/
|
|
606
|
-
│ ├──
|
|
512
|
+
│ ├── ${packageName}/ # 📚 Telescope generated code (primary reference, excluded from build)
|
|
607
513
|
│ │ ├── cosmos/ # Full cosmos SDK modules
|
|
608
514
|
│ │ │ ├── bank/ # Balance queries, transfers
|
|
609
515
|
│ │ │ ├── staking/ # Validator operations
|
|
@@ -611,7 +517,7 @@ ${packageName}-mcp/
|
|
|
611
517
|
│ │ ├── osmosis/ # Osmosis DEX functionality
|
|
612
518
|
│ │ ├── ibc/ # Inter-blockchain communication
|
|
613
519
|
│ │ └── index.ts # Main exports
|
|
614
|
-
│ ├──
|
|
520
|
+
│ ├── ${packageName}-examples/ # 📖 Production examples (excluded from build)
|
|
615
521
|
│ │ ├── config-example.ts # Chain configuration setup
|
|
616
522
|
│ │ ├── useBalance.ts # Balance query React hooks
|
|
617
523
|
│ │ ├── useBalanceFunc.ts # Direct balance functions
|
|
@@ -625,16 +531,19 @@ ${packageName}-mcp/
|
|
|
625
531
|
│ │ ├── useGrants.ts # Authorization grants
|
|
626
532
|
│ │ └── useSendData.ts # Transaction preparation
|
|
627
533
|
│ ├── prompts/ # 🤖 Agent instruction files
|
|
628
|
-
│ │ ├── codegen-usage.md #
|
|
534
|
+
│ │ ├── codegen-usage.md # Implementation guide for agents
|
|
629
535
|
│ │ ├── agent-guidelines.md # Best practices for agents
|
|
630
536
|
│ │ └── chains.json # Chain registry data
|
|
631
|
-
│
|
|
632
|
-
|
|
633
|
-
├── dist/ # Compiled JavaScript (excludes telescope/ and telescope-examples/)
|
|
537
|
+
│ └── index.ts # MCP server with function generator tool
|
|
538
|
+
├── dist/ # Compiled JavaScript (excludes ${packageName}/ and ${packageName}-examples/)
|
|
634
539
|
└── package.json
|
|
635
540
|
\`\`\`
|
|
636
541
|
|
|
637
|
-
|
|
542
|
+
**Key Points:**
|
|
543
|
+
- \`src/${packageName}/\` contains the complete telescope-generated codebase as the **primary reference**
|
|
544
|
+
- \`src/${packageName}-examples/\` contains **production examples** for patterns and logic reference
|
|
545
|
+
- Both directories are excluded from TypeScript build but available for AI agents to read
|
|
546
|
+
- Examples may contain compilation errors - focus on logic and patterns, not direct copying
|
|
638
547
|
|
|
639
548
|
Generated by [Telescope](https://github.com/hyperweb-io/telescope) 🔭
|
|
640
549
|
`;
|
|
@@ -642,7 +551,7 @@ Generated by [Telescope](https://github.com/hyperweb-io/telescope) 🔭
|
|
|
642
551
|
|
|
643
552
|
function copyTelescopeCodebase(builder: TelescopeBuilder, mcpServerPath: string, packageName: string) {
|
|
644
553
|
const sourcePath = builder.outPath;
|
|
645
|
-
const destPath = join(mcpServerPath, 'src',
|
|
554
|
+
const destPath = join(mcpServerPath, 'src', packageName);
|
|
646
555
|
|
|
647
556
|
// Copy the entire telescope generated directory
|
|
648
557
|
if (existsSync(sourcePath)) {
|
|
@@ -672,181 +581,145 @@ function copyTelescopeCodebase(builder: TelescopeBuilder, mcpServerPath: string,
|
|
|
672
581
|
|
|
673
582
|
// Removed retry logic - no longer needed since we skip copy if destination exists
|
|
674
583
|
|
|
675
|
-
function generateTelescopeLoader(packageName: string) {
|
|
676
|
-
return `import { readFileSync } from 'node:fs';
|
|
677
|
-
import { resolve, dirname } from 'node:path';
|
|
678
|
-
import { fileURLToPath } from 'node:url';
|
|
679
584
|
|
|
680
|
-
const __filename = fileURLToPath(import.meta.url);
|
|
681
|
-
const __dirname = dirname(__filename);
|
|
682
585
|
|
|
683
|
-
|
|
684
|
-
|
|
685
|
-
|
|
686
|
-
*/
|
|
687
|
-
export class TelescopeLoader {
|
|
688
|
-
private basePath: string;
|
|
586
|
+
function generateComprehensivePrompts(mcpServerPath: string, packageName: string) {
|
|
587
|
+
// Generate codegen-usage.md with our updated content
|
|
588
|
+
const codegenUsageContent = `# Codegen Usage Guide
|
|
689
589
|
|
|
690
|
-
|
|
691
|
-
|
|
692
|
-
}
|
|
590
|
+
## Overview
|
|
591
|
+
This guide provides instructions for MCP agents on how to use the telescope generated code when implementing the \`use-${packageName}\` tool.
|
|
693
592
|
|
|
694
|
-
|
|
695
|
-
* Get available modules in the telescope codebase
|
|
696
|
-
*/
|
|
697
|
-
getAvailableModules(): string[] {
|
|
698
|
-
// This would typically read the directory structure
|
|
699
|
-
// For now, return common cosmos modules
|
|
700
|
-
return [
|
|
701
|
-
'cosmos/bank/v1beta1',
|
|
702
|
-
'cosmos/staking/v1beta1',
|
|
703
|
-
'cosmos/gov/v1beta1',
|
|
704
|
-
'cosmos/distribution/v1beta1',
|
|
705
|
-
'cosmwasm/wasm/v1',
|
|
706
|
-
'ibc/core/client/v1',
|
|
707
|
-
'osmosis/gamm/v1beta1'
|
|
708
|
-
];
|
|
709
|
-
}
|
|
593
|
+
## Understanding the Structure
|
|
710
594
|
|
|
711
|
-
|
|
712
|
-
|
|
713
|
-
*/
|
|
714
|
-
loadModuleInfo(modulePath: string) {
|
|
715
|
-
try {
|
|
716
|
-
const infoPath = resolve(this.basePath, modulePath, 'README.md');
|
|
717
|
-
return readFileSync(infoPath, 'utf-8');
|
|
718
|
-
} catch (error) {
|
|
719
|
-
return \`Module documentation not found for \${modulePath}\`;
|
|
720
|
-
}
|
|
721
|
-
}
|
|
595
|
+
### Primary Reference: \`src/${packageName}/\` Directory
|
|
596
|
+
This is your **main reference** for understanding the complete telescope-generated codebase. It contains:
|
|
722
597
|
|
|
723
|
-
|
|
724
|
-
|
|
725
|
-
|
|
726
|
-
|
|
727
|
-
// Return basic schema info for the module
|
|
728
|
-
return {
|
|
729
|
-
module: modulePath,
|
|
730
|
-
package: '${packageName}',
|
|
731
|
-
queries: ['getBalance', 'getAllBalances'],
|
|
732
|
-
mutations: ['send', 'delegate'],
|
|
733
|
-
types: ['Coin', 'MsgSend', 'MsgDelegate']
|
|
734
|
-
};
|
|
735
|
-
}
|
|
736
|
-
}
|
|
598
|
+
- **Complete type definitions** for all blockchain modules
|
|
599
|
+
- **Client implementations** for queries and transactions
|
|
600
|
+
- **Generated interfaces** from protobuf definitions
|
|
601
|
+
- **All available methods** and their signatures
|
|
737
602
|
|
|
738
|
-
|
|
739
|
-
|
|
740
|
-
}
|
|
603
|
+
**Key files to understand**:
|
|
604
|
+
- \`src/${packageName}/index.ts\` - Main exports and available modules
|
|
605
|
+
- \`src/${packageName}/cosmos/\` - Cosmos SDK modules (bank, staking, gov, etc.)
|
|
606
|
+
- \`src/${packageName}/osmosis/\` - Osmosis-specific modules
|
|
607
|
+
- \`src/${packageName}/ibc/\` - Inter-blockchain communication
|
|
608
|
+
- \`src/${packageName}/README.md\` - Comprehensive documentation
|
|
741
609
|
|
|
742
|
-
|
|
743
|
-
|
|
744
|
-
const codegenUsageContent = `# Codegen Usage Guide
|
|
610
|
+
### Production Examples: \`src/${packageName}-examples/\` Directory
|
|
611
|
+
Use these as **implementation patterns** and **logic reference**:
|
|
745
612
|
|
|
746
|
-
|
|
747
|
-
|
|
613
|
+
- **Real production code** showing how to use telescope functions
|
|
614
|
+
- **Best practices** for error handling and data processing
|
|
615
|
+
- **Complete workflows** for common blockchain operations
|
|
748
616
|
|
|
749
|
-
|
|
617
|
+
**⚠️ 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.
|
|
750
618
|
|
|
751
|
-
|
|
752
|
-
These are direct async functions that make RPC calls to blockchain nodes. Use these for:
|
|
753
|
-
- Server-side operations
|
|
754
|
-
- Node.js scripts
|
|
755
|
-
- Direct blockchain queries outside React
|
|
619
|
+
## Using the MCP Tool
|
|
756
620
|
|
|
757
|
-
|
|
758
|
-
|
|
759
|
-
import { getBalance } from '${packageName}/cosmos/bank/v1beta1/query.rpc.func';
|
|
760
|
-
import { send } from '${packageName}/cosmos/bank/v1beta1/tx.rpc.func';
|
|
761
|
-
\`\`\`
|
|
621
|
+
### Single Tool: \`use-${packageName}\`
|
|
622
|
+
This MCP server provides one tool that generates implementation guidance by:
|
|
762
623
|
|
|
763
|
-
**
|
|
624
|
+
1. **Analyzing your request** (task, chain, function type)
|
|
625
|
+
2. **Finding relevant examples** from \`${packageName}-examples/\`
|
|
626
|
+
3. **Providing step-by-step guidance** using telescope patterns
|
|
627
|
+
4. **Showing proper imports** and configuration
|
|
764
628
|
|
|
765
|
-
|
|
766
|
-
\`\`\`typescript
|
|
767
|
-
import { getBalance } from '${packageName}/cosmos/bank/v1beta1/query.rpc.func';
|
|
629
|
+
## Implementation Approach
|
|
768
630
|
|
|
769
|
-
|
|
770
|
-
|
|
771
|
-
address: "cosmos1...",
|
|
772
|
-
denom: "uatom"
|
|
773
|
-
});
|
|
631
|
+
### Step 1: Understand Telescope Structure
|
|
632
|
+
When implementing a function, first explore \`src/${packageName}/\` to understand:
|
|
774
633
|
|
|
775
|
-
|
|
776
|
-
|
|
777
|
-
|
|
778
|
-
|
|
779
|
-
|
|
780
|
-
}
|
|
781
|
-
console.error('Error fetching balance:', error);
|
|
782
|
-
return null;
|
|
783
|
-
}
|
|
634
|
+
\`\`\`typescript
|
|
635
|
+
// Example: For balance queries, look at:
|
|
636
|
+
// src/${packageName}/cosmos/bank/v1beta1/query.ts - Type definitions
|
|
637
|
+
// src/${packageName}/cosmos/bank/v1beta1/query.rpc.Query.ts - Query client
|
|
638
|
+
// src/${packageName}/cosmos/bank/v1beta1/query.rpc.func.ts - Direct functions
|
|
639
|
+
// src/${packageName}/cosmos/bank/v1beta1/query.rpc.react.ts - React hooks
|
|
784
640
|
\`\`\`
|
|
785
641
|
|
|
786
|
-
### 2
|
|
787
|
-
|
|
788
|
-
- Automatic caching and refetching
|
|
789
|
-
- Loading states
|
|
790
|
-
- Error handling
|
|
791
|
-
- Integration with React Query
|
|
642
|
+
### Step 2: Reference Production Examples
|
|
643
|
+
Look at \`${packageName}-examples/\` for implementation patterns:
|
|
792
644
|
|
|
793
|
-
**Import Pattern**:
|
|
794
645
|
\`\`\`typescript
|
|
795
|
-
|
|
796
|
-
|
|
646
|
+
// Example: useBalance.ts shows the pattern for:
|
|
647
|
+
// - Proper imports from telescope
|
|
648
|
+
// - Error handling approaches
|
|
649
|
+
// - Data transformation logic
|
|
650
|
+
// - Integration with React Query
|
|
651
|
+
|
|
652
|
+
// Focus on UNDERSTANDING the logic:
|
|
653
|
+
// - How RPC endpoints are configured
|
|
654
|
+
// - How parameters are validated
|
|
655
|
+
// - How responses are processed
|
|
656
|
+
// - How errors are handled
|
|
797
657
|
\`\`\`
|
|
798
658
|
|
|
799
|
-
|
|
659
|
+
### Step 3: Generate Your Implementation
|
|
660
|
+
Use the patterns from both directories to create your function:
|
|
800
661
|
|
|
801
|
-
### Import Chain Registry Data
|
|
802
662
|
\`\`\`typescript
|
|
803
|
-
|
|
663
|
+
// Your implementation should:
|
|
664
|
+
// 1. Use proper imports from the telescope codebase
|
|
665
|
+
// 2. Follow error handling patterns from examples
|
|
666
|
+
// 3. Include proper TypeScript types
|
|
667
|
+
// 4. Handle edge cases shown in examples
|
|
804
668
|
\`\`\`
|
|
805
669
|
|
|
806
|
-
|
|
807
|
-
\`\`\`typescript
|
|
808
|
-
// Define your target chain
|
|
809
|
-
export const defaultChainName = 'cosmos'; // or 'osmosis', 'injective', etc.
|
|
810
|
-
|
|
811
|
-
// Find chain info from registry
|
|
812
|
-
export const defaultChain = chains.find((chain) => chain.chainName === defaultChainName);
|
|
813
|
-
|
|
814
|
-
// Get RPC endpoint
|
|
815
|
-
export const defaultRpcEndpoint = defaultChain?.apis?.rpc?.[0]?.address || 'http://localhost:26657';
|
|
816
|
-
\`\`\`
|
|
670
|
+
## Category of Functions in Telescope
|
|
817
671
|
|
|
818
|
-
|
|
672
|
+
### 1. **query.rpc.func.ts** - Direct Function Calls
|
|
673
|
+
- Server-side operations
|
|
674
|
+
- Node.js scripts
|
|
675
|
+
- Direct blockchain queries
|
|
819
676
|
|
|
820
|
-
###
|
|
821
|
-
|
|
677
|
+
### 2. **query.rpc.react.ts** - React Hooks
|
|
678
|
+
- Frontend applications
|
|
679
|
+
- Automatic caching and refetching
|
|
680
|
+
- Loading states and error handling
|
|
822
681
|
|
|
823
|
-
###
|
|
824
|
-
|
|
825
|
-
-
|
|
826
|
-
- Handling errors and returning proper MCP responses
|
|
827
|
-
- Working with blockchain data in MCP context
|
|
682
|
+
### 3. **tx.rpc.func.ts** - Transaction Functions
|
|
683
|
+
- Broadcasting transactions
|
|
684
|
+
- Message composition
|
|
828
685
|
|
|
829
|
-
|
|
686
|
+
### 4. **tx.rpc.react.ts** - Transaction Hooks
|
|
687
|
+
- Transaction broadcasting in React
|
|
688
|
+
- Transaction state management
|
|
830
689
|
|
|
831
|
-
##
|
|
690
|
+
## Chain Configuration Pattern
|
|
832
691
|
|
|
833
|
-
|
|
834
|
-
- **Use .rpc.func** for: Server-side scripts, CLI tools, backend services
|
|
835
|
-
- **Use .rpc.react** for: React applications, frontend components with state management
|
|
692
|
+
Always reference \`config-example.ts\` for proper setup:
|
|
836
693
|
|
|
837
|
-
### Error Handling Patterns
|
|
838
694
|
\`\`\`typescript
|
|
839
|
-
|
|
840
|
-
|
|
841
|
-
|
|
842
|
-
|
|
843
|
-
|
|
844
|
-
|
|
845
|
-
return null; // Handle account not found
|
|
846
|
-
}
|
|
847
|
-
throw error; // Re-throw other errors
|
|
848
|
-
}
|
|
695
|
+
import { assetLists, chains } from "@chain-registry/v2";
|
|
696
|
+
|
|
697
|
+
export const targetChainName = 'cosmos';
|
|
698
|
+
export const rpcEndpoint = 'https://cosmos-rpc.quickapi.com:443';
|
|
699
|
+
export const chain = chains.find((chain) => chain.chainName === targetChainName);
|
|
700
|
+
export const assetList = assetLists.find((assetList) => assetList.chainName === targetChainName);
|
|
849
701
|
\`\`\`
|
|
702
|
+
|
|
703
|
+
## Important Guidelines
|
|
704
|
+
|
|
705
|
+
### When Using Examples
|
|
706
|
+
- **Study the logic**, don't copy/paste directly
|
|
707
|
+
- **Understand the patterns** for imports and usage
|
|
708
|
+
- **Learn from error handling** approaches
|
|
709
|
+
- **Adapt the structure** to your specific needs
|
|
710
|
+
|
|
711
|
+
### When Using Telescope Codebase
|
|
712
|
+
- **Browse the generated files** to understand available methods
|
|
713
|
+
- **Check type definitions** for proper parameter structures
|
|
714
|
+
- **Look at client implementations** for usage patterns
|
|
715
|
+
- **Reference documentation** in README.md files
|
|
716
|
+
|
|
717
|
+
### Best Practices
|
|
718
|
+
1. Always include comprehensive error handling
|
|
719
|
+
2. Validate input parameters before making calls
|
|
720
|
+
3. Convert base units to human-readable amounts when needed
|
|
721
|
+
4. Use proper TypeScript types from telescope
|
|
722
|
+
5. Test your implementations thoroughly
|
|
850
723
|
`;
|
|
851
724
|
|
|
852
725
|
writeFileSync(join(mcpServerPath, 'src', 'prompts', 'codegen-usage.md'), codegenUsageContent);
|
|
@@ -1014,17 +887,16 @@ function generateTelescopeExamples(mcpServerPath: string, packageName: string) {
|
|
|
1014
887
|
content: `import { assetLists, chains } from "@chain-registry/v2";
|
|
1015
888
|
|
|
1016
889
|
/**
|
|
890
|
+
* Chain configuration example
|
|
1017
891
|
* mainnet: 'cosmos'
|
|
1018
|
-
* testnet: 'cosmoshub-testnet'
|
|
892
|
+
* testnet: 'cosmoshub-testnet'
|
|
1019
893
|
* mainnet rpc: 'https://cosmos-rpc.quickapi.com:443'
|
|
1020
894
|
* testnet rpc: 'https://rpc.testnet.cosmos.network:443'
|
|
1021
895
|
*/
|
|
1022
|
-
export const
|
|
1023
|
-
export const
|
|
1024
|
-
|
|
1025
|
-
export const
|
|
1026
|
-
|
|
1027
|
-
export const defaultAssetList = assetLists.find((assetList) => assetList.chainName === defaultChainName)
|
|
896
|
+
export const targetChainName = 'cosmos';
|
|
897
|
+
export const rpcEndpoint = 'https://cosmos-rpc.quickapi.com:443';
|
|
898
|
+
export const chain = chains.find((chain) => chain.chainName === targetChainName);
|
|
899
|
+
export const assetList = assetLists.find((assetList) => assetList.chainName === targetChainName);
|
|
1028
900
|
`
|
|
1029
901
|
},
|
|
1030
902
|
{
|
|
@@ -1896,7 +1768,7 @@ export const useTotalAssets = (chainName: string) => {
|
|
|
1896
1768
|
|
|
1897
1769
|
// Write all example files
|
|
1898
1770
|
exampleFiles.forEach(({ name, content }) => {
|
|
1899
|
-
writeFileSync(join(mcpServerPath, 'src',
|
|
1771
|
+
writeFileSync(join(mcpServerPath, 'src', `${packageName}-examples`, name), content);
|
|
1900
1772
|
});
|
|
1901
1773
|
}
|
|
1902
1774
|
|
|
@@ -134,7 +134,7 @@ function getTypesForPackage(builder: TelescopeBuilder, packageName: string): Arr
|
|
|
134
134
|
}
|
|
135
135
|
|
|
136
136
|
export const plugin = (builder: TelescopeBuilder) => {
|
|
137
|
-
if (!builder.options
|
|
137
|
+
if (!builder.options?.readme?.enabled && !builder.options?.mcpServer?.enabled) {
|
|
138
138
|
return;
|
|
139
139
|
}
|
|
140
140
|
|