feat: adding basic Starknet integration // WIP

Author: wayzeek

README.md

@@ -1,10 +1,11 @@
-# @mcpdotdirect/create-mcp-server
+# Starknet MCP Server
 
 ![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)
 ![TypeScript](https://img.shields.io/badge/TypeScript-5.0+-3178C6)
 ![MCP](https://img.shields.io/badge/MCP-1.7+-green)
+![Starknet.js](https://img.shields.io/badge/Starknet.js-Latest-purple)
 
-A CLI tool to create a new Model Context Protocol (MCP) server project. This package provides a template for building custom MCP servers that can be used by AI agents to interact with external systems and data sources.
+An MCP (Model Context Protocol) server for the Starknet blockchain. This server provides AI agents with the ability to interact with Starknet networks, query blockchain data, manage wallets, and interact with smart contracts.
 
 ## 📋 Usage
 
@@ -31,16 +32,17 @@ The template includes:
 
 ## ✨ Features
 
-- **Dual Transport Support**: Run your MCP server over stdio or HTTP
-- **TypeScript**: Full TypeScript support for type safety
-- **MCP SDK**: Built on the official Model Context Protocol SDK
-- **Extensible**: Easy to add custom tools, resources, and prompts
+- **Starknet Integration**: Full Starknet blockchain integration using Starknet.js
+- **Network Support**: Supports both Mainnet and Sepolia testnet
+- **StarknetID Integration**: Resolution of Starknet IDs to addresses and vice versa
+- **Native Token Support**: Support for both ETH and STRK native tokens
+- **Smart Contract Interaction**: Call and query Starknet smart contracts
+- **Dual Transport**: Run as stdio server or HTTP server for different integration needs
+- **AI-Ready**: Designed to be used with Claude, GPT, and other AI assistants
 
 ## 🚀 Getting Started
 
-After creating your project:
-
-1. Install dependencies using your preferred package manager:
+1. Install dependencies:
    ```bash
    # Using npm
    npm install
@@ -73,44 +75,75 @@ After creating your project:
    npm run dev:http
    ```
 
-> **Note**: The default scripts in package.json use Bun as the runtime (e.g., `bun run src/index.ts`). If you prefer to use a different package manager or runtime, you can modify these scripts in your package.json file to use Node.js or another runtime of your choice.
+## 🔧 Supported Features
+
+### Blockchain Information
+- Query chain information (chain ID, latest block)
+- Explore block details
+- Search transactions
+- Get address information
+
+### Native Token Operations
+- Get ETH and STRK balances
+- Transfer tokens
+
+### Smart Contract Interaction
+- Call read-only contract functions
+- Get contract storage information
+- View ABIs and contract class information
+
+### StarknetID
+- Resolve Starknet addresses to Starknet IDs
+- Resolve Starknet IDs to addresses
+- Get Starknet ID profiles
+
+### NFT Operations
+- Check NFT ownership
+- Get NFT collection information
+
+## 🔍 Usage with AI Assistants
+
+When using this server with AI assistants like Claude or GPT:
+
+1. Configure your AI assistant to use this MCP server
+2. The assistant can then use tools to interact with Starknet
+3. Example: "Look up the Starknet ID for address 0x123..."
+
+## 📦 API Structure
 
-## 🛠️ Adding Custom Tools and Resources
+The server provides:
 
-When adding custom tools, resources, or prompts to your MCP server:
+- **Tools**: Direct function calls to perform blockchain operations
+- **Resources**: Structured data endpoints in the form of starknet://{network}/...
+- **Prompts**: Pre-built prompts to help AI agents explore the Starknet blockchain
+
+## 🛠️ Development Conventions
+
+When adding custom tools, resources, or prompts:
 
 1. Use underscores (`_`) instead of hyphens (`-`) in all resource, tool, and prompt names
    ```typescript
    // Good: Uses underscores
    server.tool(
-     "my_custom_tool",
-     "Description of my custom tool",
-     {
-       param_name: z.string().describe("Parameter description")
-     },
-     async (params) => {
-       // Tool implementation
-     }
-   );
-   
-   // Bad: Uses hyphens, may cause issues with Cursor
-   server.tool(
-     "my-custom-tool",
-     "Description of my custom tool",
+     "starknet_contract_call",
+     "Description of the tool",
      {
-       param-name: z.string().describe("Parameter description")
+       contract_address: z.string().describe("The contract address")
      },
      async (params) => {
        // Tool implementation
      }
    );
    ```
 
-2. This naming convention ensures compatibility with Cursor and other AI tools that interact with your MCP server
+2. This naming convention ensures compatibility with Cursor and other AI tools
 
 ## 📚 Documentation
 
-For more information about the Model Context Protocol, visit the [MCP Documentation](https://modelcontextprotocol.io/introduction).
+For more information about:
+- [Model Context Protocol](https://modelcontextprotocol.io/introduction)
+- [Starknet.js Documentation](https://www.starknetjs.com/)
+- [Starknet Documentation](https://docs.starknet.io/)
 
 ## 📄 License
 

package.json

@@ -55,7 +55,7 @@
     "ai",
     "agent"
   ],
-  "author": "mcpdotdirect",
+  "author": "Etheral <[email protected]>",
   "license": "MIT",
   "engines": {
     "node": ">=18.0.0"

src/core/chains.ts

@@ -0,0 +1,67 @@
+/**
+ * Defines supported Starknet networks with their RPC URLs
+ */
+
+export type NetworkConfig = {
+  name: string;
+  chainId: string;
+  rpcUrl: string;
+};
+
+// Network configurations
+const networks: Record<string, NetworkConfig> = {
+  mainnet: {
+    name: 'mainnet',
+    chainId: 'SN_MAIN',
+    rpcUrl: 'https://starknet-mainnet.public.blastapi.io'
+  },
+  sepolia: {
+    name: 'sepolia',
+    chainId: 'SN_SEPOLIA',
+    rpcUrl: 'https://starknet-sepolia.public.blastapi.io'
+  }
+};
+
+// Default network to use if none specified
+export const DEFAULT_NETWORK = 'mainnet';
+
+/**
+ * Get the network configuration for a given network name
+ * @param networkName The network name (mainnet, sepolia)
+ * @returns The network configuration
+ */
+export function getNetwork(networkName: string = DEFAULT_NETWORK): NetworkConfig {
+  const network = networks[networkName.toLowerCase()];
+  
+  if (!network) {
+    throw new Error(`Network ${networkName} not supported. Available networks: ${Object.keys(networks).join(', ')}`);
+  }
+  
+  return network;
+}
+
+/**
+ * Get the RPC URL for a given network
+ * @param networkName The network name
+ * @returns The RPC URL for the network
+ */
+export function getRpcUrl(networkName: string = DEFAULT_NETWORK): string {
+  return getNetwork(networkName).rpcUrl;
+}
+
+/**
+ * Get the chain ID for a given network
+ * @param networkName The network name
+ * @returns The chain ID for the network
+ */
+export function getChainId(networkName: string = DEFAULT_NETWORK): string {
+  return getNetwork(networkName).chainId;
+}
+
+/**
+ * Get a list of all supported networks
+ * @returns Array of network names
+ */
+export function getSupportedNetworks(): string[] {
+  return Object.keys(networks);
+} 

src/core/prompts.ts

@@ -2,25 +2,109 @@ import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { z } from "zod";
 
 /**
- * Register all prompts with the MCP server
+ * Register all Starknet-related prompts with the MCP server
  * @param server The MCP server instance
  */
 export function registerPrompts(server: McpServer) {
-  // Example prompt
+  // Basic block explorer prompt
   server.prompt(
-    "greeting",
-    "A simple greeting prompt",
+    "explore_starknet_block",
+    "Explore information about a specific Starknet block",
     {
-      name: z.string().describe("Name to greet")
+      blockNumber: z.string().optional().describe("Block number to explore. If not provided, latest block will be used."),
+      network: z.string().optional().describe("Network name (e.g., 'mainnet', 'sepolia'). Defaults to Mainnet.")
     },
-    (params: { name: string }) => ({
+    ({ blockNumber, network = "mainnet" }) => ({
       messages: [{
         role: "user",
         content: {
           type: "text",
-          text: `Hello, ${params.name}! How can I help you today?`
+          text: `I want to explore the Starknet blockchain. Please give me detailed information about ${blockNumber ? `block #${blockNumber}` : "the latest block"} on the ${network} network. Include data like timestamp, transactions count, and any other interesting metrics.`
         }
       }]
     })
   );
-}
+  
+  // Address information prompt
+  server.prompt(
+    "explore_starknet_address",
+    "Get information about a Starknet address",
+    {
+      address: z.string().describe("Starknet address to explore"),
+      network: z.string().optional().describe("Network name (e.g., 'mainnet', 'sepolia'). Defaults to Mainnet.")
+    },
+    ({ address, network = "mainnet" }) => ({
+      messages: [{
+        role: "user",
+        content: {
+          type: "text",
+          text: `I'm researching the Starknet address ${address} on the ${network} network. Please provide me with detailed information about this address, including its ETH balance, any token balances if available, and transaction history if possible. Also check if it has a Starknet ID associated with it. Summarize what you find about this address.`
+        }
+      }]
+    })
+  );
+  
+  // Transaction information prompt
+  server.prompt(
+    "explore_starknet_transaction",
+    "Get information about a Starknet transaction",
+    {
+      txHash: z.string().describe("Transaction hash to explore"),
+      network: z.string().optional().describe("Network name (e.g., 'mainnet', 'sepolia'). Defaults to Mainnet.")
+    },
+    ({ txHash, network = "mainnet" }) => ({
+      messages: [{
+        role: "user",
+        content: {
+          type: "text",
+          text: `I'm analyzing Starknet transaction ${txHash} on the ${network} network. Please provide me with detailed information about this transaction, including its status, block confirmation, timestamp, gas used, and any other relevant details. Also explain what this transaction did in plain language.`
+        }
+      }]
+    })
+  );
+  
+  // Starknet ID lookup prompt
+  server.prompt(
+    "lookup_starknet_id",
+    "Look up a Starknet ID or resolve an address to a Starknet ID",
+    {
+      identifier: z.string().describe("Either a Starknet ID (with or without .stark) or a Starknet address"),
+      network: z.string().optional().describe("Network name (e.g., 'mainnet', 'sepolia'). Defaults to Mainnet.")
+    },
+    ({ identifier, network = "mainnet" }) => {
+      // Determine if this is an address or a Starknet ID
+      const isLikelyAddress = identifier.startsWith('0x') || /^[0-9a-fA-F]{64}$/.test(identifier);
+      
+      return {
+        messages: [{
+          role: "user",
+          content: {
+            type: "text",
+            text: isLikelyAddress 
+              ? `Please lookup the Starknet ID associated with the address ${identifier} on the ${network} network. If there's a profile available, provide details about it.`
+              : `Please resolve the Starknet ID "${identifier}" to an address on the ${network} network. If this is a valid ID, provide information about the associated address.`
+          }
+        }]
+      };
+    }
+  );
+  
+  // Starknet ID profile prompt
+  server.prompt(
+    "explore_starknet_id_profile",
+    "Explore a full Starknet ID profile",
+    {
+      address: z.string().describe("Starknet address to look up the profile for"),
+      network: z.string().optional().describe("Network name (e.g., 'mainnet', 'sepolia'). Defaults to Mainnet.")
+    },
+    ({ address, network = "mainnet" }) => ({
+      messages: [{
+        role: "user",
+        content: {
+          type: "text",
+          text: `I'd like to explore the Starknet ID profile for address ${address} on the ${network} network. Please provide all available information, including the ID, profile picture, verifications, and any other associated data. Let me know if this address has a verified profile and what it can be used for.`
+        }
+      }]
+    })
+  );
+}