@kasarlabs/mcp-doc-mcp 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Kasar Labs
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,202 @@
+# MCP Doc Server
+
+Documentation and discovery MCP server for Ask Starknet. This MCP provides tools to explore Ask Starknet's architecture, capabilities, project ideas, and usage guide.
+
+## Features
+
+- **Quick Start Guide**: Get help on how to use Ask Starknet with setup instructions and best practices
+- **Architecture Explanation**: Understand how Ask Starknet's unified router and MCP servers work together
+- **Capabilities Listing**: Discover all available MCPs organized by domains (wallets, DeFi, blockchain, dev-tools, special)
+- **Project Ideas**: Get inspired with project ideas that can be built using Ask Starknet
+
+## Installation
+
+```bash
+npx -y @kasarlabs/mcp-doc-mcp
+```
+
+## Available Tools
+
+### 1. `mcp_doc_help`
+
+Get comprehensive help on using Ask Starknet, including quick start guide, setup instructions, best practices, and troubleshooting.
+
+**Parameters:**
+
+None (empty object)
+
+**Example:**
+
+```json
+{}
+```
+
+**Response:**
+
+Returns a markdown-formatted help guide with:
+
+- What is Ask Starknet
+- Quick start examples
+- Setup instructions (minimal and full)
+- Best practices
+- Troubleshooting tips
+
+```json
+{
+  "status": "success",
+  "data": "# Ask Starknet Help Guide\n\nWelcome to Ask Starknet!..."
+}
+```
+
+### 2. `mcp_doc_explain_architecture`
+
+Explains the Ask Starknet architecture and how it works.
+
+**Parameters:**
+
+- `topic` (optional): `"router"` | `"mcps"` | `"interaction"` | `"all"`
+
+**Example:**
+
+```json
+{
+  "topic": "router"
+}
+```
+
+**Response:**
+
+```json
+{
+  "status": "success",
+  "data": {
+    "overview": "...",
+    "unifiedRouter": {
+      "description": "...",
+      "howItWorks": "...",
+      "technologies": [...]
+    }
+  }
+}
+```
+
+### 3. `mcp_doc_list_capabilities`
+
+Lists all Ask Starknet capabilities organized by domains.
+
+**Parameters:**
+
+- `domain` (optional): `"wallets"` | `"defi"` | `"blockchain"` | `"dev-tools"` | `"special"` | `"all"`
+- `mcp` (optional): Filter by specific MCP name (e.g., `"avnu"`, `"erc20"`)
+
+**Example:**
+
+```json
+{
+  "domain": "defi"
+}
+```
+
+**Response:**
+
+```json
+{
+  "status": "success",
+  "data": {
+    "domains": {
+      "defi": {
+        "description": "...",
+        "mcps": {
+          "avnu": {
+            "description": "...",
+            "tools": [...],
+            "expertise": "...",
+            "toolCount": 2
+          }
+        }
+      }
+    },
+    "statistics": {
+      "totalMCPs": 20,
+      "totalTools": 150,
+      "mcpsByDomain": {...}
+    }
+  }
+}
+```
+
+### 4. `mcp_doc_suggest_projects`
+
+Suggests project ideas that can be built with Ask Starknet.
+
+**Parameters:**
+
+- `domain` (optional): `"defi"` | `"nft"` | `"trading"` | `"automation"` | `"analytics"` | `"gaming"` | `"all"`
+- `mcps` (optional): Filter projects using specific MCPs (e.g., `["avnu", "ekubo"]`)
+
+**Example:**
+
+```json
+{
+  "domain": "defi",
+  "mcps": ["avnu", "ekubo"]
+}
+```
+
+**Response:**
+
+```json
+{
+  "status": "success",
+  "data": {
+    "projects": [
+      {
+        "name": "Multi-DEX Swap Aggregator",
+        "description": "...",
+        "domain": "defi",
+        "requiredMCPs": ["avnu", "ekubo", "fibrous"],
+        "features": [...]
+      }
+    ],
+    "totalProjects": 5
+  }
+}
+```
+
+## Domains
+
+Ask Starknet organizes MCPs into the following domains:
+
+- **Wallets**: `argent`, `braavos`, `okx`, `openzeppelin`
+- **DeFi**: `avnu`, `ekubo`, `endurfi`, `extended`, `fibrous`, `opus`, `vesu`, `unruggable`
+- **Blockchain**: `erc20`, `erc721`, `transaction`, `starknet-rpc`, `contract`
+- **Dev Tools**: `scarb`, `cairo-coder`
+- **Special**: `artpeace`
+
+## Development
+
+### Build
+
+```bash
+pnpm install
+pnpm build
+```
+
+The build process compiles TypeScript and copies resource files to the build directory.
+
+## Architecture
+
+This MCP is designed to be completely standalone with no blockchain dependencies. It uses:
+
+- **Static resources**: Help guide, architecture docs, and capabilities are stored as markdown files in `src/resources/`
+- **Static project ideas**: Curated list of project ideas
+- **No external dependencies**: All data is bundled with the MCP for offline access
+
+## License
+
+MIT
+
+## Support
+
+- GitHub Issues: [Create an issue](https://github.com/kasarlabs/ask-starknet/issues)
+- Documentation: [docs.kasar.io](https://docs.kasar.io)

package/bin/mcp-doc-mcp.js

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+import('../build/index.js').catch(console.error);

package/build/index.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export declare const RegisterToolInServer: () => Promise<void>;

package/build/index.js

@@ -0,0 +1,57 @@
+#!/usr/bin/env node
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import * as dotenv from 'dotenv';
+import { registerToolsWithServer } from '@kasarlabs/ask-starknet-core';
+import { explainArchitecture } from './tools/explainArchitecture.js';
+import { listCapabilities } from './tools/listCapabilities.js';
+import { suggestProjects } from './tools/suggestProjects.js';
+import { getHelp } from './tools/getHelp.js';
+import { explainArchitectureSchema, listCapabilitiesSchema, suggestProjectsSchema, getHelpSchema, } from './schemas/index.js';
+dotenv.config();
+const server = new McpServer({
+    name: 'mcp-doc-mcp',
+    version: '0.1.0',
+});
+const registerTools = (DocsToolRegistry) => {
+    DocsToolRegistry.push({
+        name: 'mcp_doc_explain_architecture',
+        description: 'Explain the Ask Starknet architecture, unified router AI-powered routing, MCP servers structure, and how they interact together',
+        schema: explainArchitectureSchema,
+        execute: explainArchitecture,
+    });
+    DocsToolRegistry.push({
+        name: 'mcp_doc_list_capabilities',
+        description: 'List all Ask Starknet capabilities organized by domains (wallets, DeFi, blockchain, dev-tools, special) with available MCPs and their tools',
+        schema: listCapabilitiesSchema,
+        execute: listCapabilities,
+    });
+    DocsToolRegistry.push({
+        name: 'mcp_doc_suggest_projects',
+        description: 'Suggest project ideas that can be built with Ask Starknet, filtered by domain or required MCPs',
+        schema: suggestProjectsSchema,
+        execute: suggestProjects,
+    });
+    DocsToolRegistry.push({
+        name: 'mcp_doc_help',
+        description: 'Get help on how to use Ask Starknet: quick start guide, setup instructions, capabilities overview, and troubleshooting',
+        schema: getHelpSchema,
+        execute: getHelp,
+    });
+};
+export const RegisterToolInServer = async () => {
+    const tools = [];
+    registerTools(tools);
+    await registerToolsWithServer(server, tools);
+};
+async function main() {
+    const transport = new StdioServerTransport();
+    await RegisterToolInServer();
+    await server.connect(transport);
+    console.error('MCP Doc Server running on stdio');
+}
+main().catch((error) => {
+    console.error('Fatal error in main():', error);
+    process.exit(1);
+});
+//# sourceMappingURL=index.js.map

package/build/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AACA,OAAO,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AACpE,OAAO,EAAE,oBAAoB,EAAE,MAAM,2CAA2C,CAAC;AACjF,OAAO,KAAK,MAAM,MAAM,QAAQ,CAAC;AAEjC,OAAO,EAAW,uBAAuB,EAAE,MAAM,8BAA8B,CAAC;AAChF,OAAO,EAAE,mBAAmB,EAAE,MAAM,gCAAgC,CAAC;AACrE,OAAO,EAAE,gBAAgB,EAAE,MAAM,6BAA6B,CAAC;AAC/D,OAAO,EAAE,eAAe,EAAE,MAAM,4BAA4B,CAAC;AAC7D,OAAO,EAAE,OAAO,EAAE,MAAM,oBAAoB,CAAC;AAC7C,OAAO,EACL,yBAAyB,EACzB,sBAAsB,EACtB,qBAAqB,EACrB,aAAa,GACd,MAAM,oBAAoB,CAAC;AAE5B,MAAM,CAAC,MAAM,EAAE,CAAC;AAEhB,MAAM,MAAM,GAAG,IAAI,SAAS,CAAC;IAC3B,IAAI,EAAE,aAAa;IACnB,OAAO,EAAE,OAAO;CACjB,CAAC,CAAC;AAEH,MAAM,aAAa,GAAG,CAAC,gBAA2B,EAAE,EAAE;IACpD,gBAAgB,CAAC,IAAI,CAAC;QACpB,IAAI,EAAE,8BAA8B;QACpC,WAAW,EACT,iIAAiI;QACnI,MAAM,EAAE,yBAAyB;QACjC,OAAO,EAAE,mBAAmB;KAC7B,CAAC,CAAC;IAEH,gBAAgB,CAAC,IAAI,CAAC;QACpB,IAAI,EAAE,2BAA2B;QACjC,WAAW,EACT,6IAA6I;QAC/I,MAAM,EAAE,sBAAsB;QAC9B,OAAO,EAAE,gBAAgB;KAC1B,CAAC,CAAC;IAEH,gBAAgB,CAAC,IAAI,CAAC;QACpB,IAAI,EAAE,0BAA0B;QAChC,WAAW,EACT,gGAAgG;QAClG,MAAM,EAAE,qBAAqB;QAC7B,OAAO,EAAE,eAAe;KACzB,CAAC,CAAC;IAEH,gBAAgB,CAAC,IAAI,CAAC;QACpB,IAAI,EAAE,cAAc;QACpB,WAAW,EACT,wHAAwH;QAC1H,MAAM,EAAE,aAAa;QACrB,OAAO,EAAE,OAAO;KACjB,CAAC,CAAC;AACL,CAAC,CAAC;AAEF,MAAM,CAAC,MAAM,oBAAoB,GAAG,KAAK,IAAI,EAAE;IAC7C,MAAM,KAAK,GAAc,EAAE,CAAC;IAC5B,aAAa,CAAC,KAAK,CAAC,CAAC;IACrB,MAAM,uBAAuB,CAAC,MAAM,EAAE,KAAK,CAAC,CAAC;AAC/C,CAAC,CAAC;AAEF,KAAK,UAAU,IAAI;IACjB,MAAM,SAAS,GAAG,IAAI,oBAAoB,EAAE,CAAC;IAE7C,MAAM,oBAAoB,EAAE,CAAC;IAC7B,MAAM,MAAM,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC;IAChC,OAAO,CAAC,KAAK,CAAC,iCAAiC,CAAC,CAAC;AACnD,CAAC;AAED,IAAI,EAAE,CAAC,KAAK,CAAC,CAAC,KAAK,EAAE,EAAE;IACrB,OAAO,CAAC,KAAK,CAAC,wBAAwB,EAAE,KAAK,CAAC,CAAC;IAC/C,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;AAClB,CAAC,CAAC,CAAC"}

package/build/resources/architecture.md

@@ -0,0 +1,369 @@
+# Ask Starknet Architecture
+
+Ask Starknet is built on a modular, AI-powered architecture that provides intelligent routing to specialized MCP servers for Starknet blockchain operations.
+
+## Overview
+
+The system consists of three main layers:
+
+1. **Unified MCP Router** - AI-powered request routing
+2. **Specialized MCP Servers** - Domain-specific tool execution
+3. **Core Utilities** - Shared interfaces and utilities
+
+## Architecture Diagram
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│                        User Request                         │
+│                  (Natural Language Input)                   │
+└────────────────────────┬────────────────────────────────────┘
+                         │
+                         v
+┌─────────────────────────────────────────────────────────────┐
+│                   Unified MCP Router                        │
+│                  (packages/mcp/)                            │
+│                                                             │
+│  ┌───────────────────────────────────────────────────────┐ │
+│  │  LangGraph AI-Powered Routing                         │ │
+│  │  - Selector Agent: Analyzes request intent            │ │
+│  │  - Specialized Agent Dispatcher: Routes to MCP        │ │
+│  └───────────────────────────────────────────────────────┘ │
+└────────────────────────┬────────────────────────────────────┘
+                         │
+                         v
+         ┌───────────────┴───────────────┐
+         │                               │
+    ┌────v────┐                    ┌────v────┐
+    │ Wallet  │                    │  DeFi   │
+    │  MCPs   │                    │  MCPs   │
+    └────┬────┘                    └────┬────┘
+         │                               │
+    ┌────v────────┐              ┌──────v──────┐
+    │ • argent    │              │ • avnu      │
+    │ • braavos   │              │ • ekubo     │
+    │ • okx       │              │ • fibrous   │
+    │ • openzeppelin│            │ • opus      │
+    └─────────────┘              │ • vesu      │
+                                 │ • endurfi   │
+                                 │ • extended  │
+                                 │ • unruggable│
+                                 └─────────────┘
+         │                               │
+         v                               v
+┌─────────────────────────────────────────────────────────────┐
+│                 Starknet Blockchain                         │
+└─────────────────────────────────────────────────────────────┘
+```
+
+## Components
+
+### 1. Unified MCP Router (`packages/mcp/`)
+
+The router is the entry point that orchestrates the entire system using LangChain/LangGraph.
+
+**Key Features:**
+
+- **AI-Powered Analysis:** Uses LLM to understand user intent
+- **Automatic Routing:** Selects the most appropriate specialized MCP
+- **State Management:** Tracks conversation history and context
+- **Environment Propagation:** Dynamically passes required env vars to specialized MCPs
+
+**Required Environment Variables:**
+
+- At least one of: `ANTHROPIC_API_KEY`, `GEMINI_API_KEY`, `OPENAI_API_KEY`
+- All environment variables required by specialized MCPs (dynamically loaded)
+
+**Core Files:**
+
+- `src/graph/graph.ts` - LangGraph workflow definition
+- `src/graph/agents/selector.ts` - Agent selection logic
+- `src/graph/agents/specialized.ts` - Specialized MCP execution
+- `src/graph/mcps/utilities.ts` - MCP configuration loading
+- `mcps.json` - Central registry of all MCPs and their configurations
+
+### 2. Specialized MCP Servers (`packages/mcps/`)
+
+Each specialized MCP server focuses on a specific domain or protocol.
+
+**Standard Structure:**
+
+```
+packages/mcps/<mcp-name>/
+├── src/
+│   ├── tools/          # Individual tool implementations
+│   ├── schemas/        # Zod validation schemas
+│   ├── lib/            # Utilities, types, constants, ABIs
+│   └── index.ts        # MCP server setup and tool registration
+├── bin/
+│   └── <mcp-name>.js   # Executable entry point
+└── package.json
+```
+
+**Tool Response Format:**
+All tools return JSON strings with consistent structure:
+
+```typescript
+{
+  status: 'success' | 'failure',
+  data?: any,        // For successful operations
+  error?: string     // For failures
+}
+```
+
+**Example MCPs by Domain:**
+
+**Wallets:**
+
+- `argent` - Argent X wallet creation and deployment
+- `braavos` - Braavos wallet operations
+- `okx` - OKX wallet integration
+- `openzeppelin` - OpenZeppelin account contracts
+
+**DeFi:**
+
+- `avnu` - DEX aggregator for optimal swap routes
+- `ekubo` - Concentrated liquidity AMM
+- `fibrous` - Multi-DEX swap routing
+- `opus` - CDP (Collateralized Debt Position) and borrowing
+- `vesu` - Lending and yield farming
+- `endurfi` - Liquid staking (xSTRK, xyWBTC)
+- `extended` - Perpetuals trading with leverage
+- `unruggable` - Memecoin creation and liquidity locking
+
+**Blockchain Operations:**
+
+- `erc20` - Token transfers, approvals, balances
+- `erc721` - NFT operations
+- `starknet-rpc` - Direct RPC calls to Starknet
+- `transaction` - Transaction simulation and monitoring
+- `contract` - Smart contract declaration and deployment
+
+**Development Tools:**
+
+- `scarb` - Cairo compilation and proving
+- `cairo-coder` - AI-powered Cairo development assistance
+- `mcp-doc` - Documentation and help system
+
+**Special:**
+
+- `artpeace` - Collaborative pixel art canvas
+
+### 3. Core Package (`packages/core/`)
+
+Provides shared utilities and interfaces used across all MCPs.
+
+**Key Exports:**
+
+```typescript
+// Tool interface definition
+export interface mcpTool<P = any> {
+  name: string;
+  description: string;
+  schema?: z.AnyZodObject;
+  execute: (params: P) => Promise<unknown>;
+}
+
+// Utility to register tools with MCP server
+export function registerToolsWithServer(
+  server: McpServer,
+  tools: mcpTool[]
+): Promise<void>;
+
+// Onchain read utilities
+export function getOnchainRead(): {
+  provider: RpcProvider;
+  account: Account;
+};
+```
+
+## Request Flow
+
+### Step 1: User Request
+
+User submits a natural language request through their MCP client (e.g., Claude Desktop).
+
+### Step 2: Router Analysis
+
+The unified router receives the request and uses the **Selector Agent**:
+
+```typescript
+// From selector.ts
+const selectorAgent = async (state) => {
+  // Analyze user input with LLM
+  const response = await llm.invoke([
+    systemPrompt, // Contains available agents and their expertise
+    userInput, // User's request
+  ]);
+
+  // Returns selected agent name or END
+  return { next: selectedAgent };
+};
+```
+
+### Step 3: Specialized Execution
+
+The **Specialized Agent** loads the selected MCP and executes tools:
+
+```typescript
+// From specialized.ts
+const specializedNode = async (state) => {
+  // Load MCP client for selected agent
+  const client = new MultiServerMCPClient({
+    [agentName]: getMCPClientConfig(agentName, env),
+  });
+
+  // Get tools and bind to LLM
+  const tools = await client.getTools();
+  const model = llm.bindTools(tools);
+
+  // Execute with LLM
+  const response = await model.invoke(messages);
+
+  // Execute tools if needed
+  if (response.tool_calls) {
+    const toolResults = await toolNode.invoke({ messages });
+    const finalResponse = await model.invoke([...messages, toolResults]);
+  }
+
+  return { messages: [finalResponse] };
+};
+```
+
+### Step 4: Tool Execution
+
+The specialized MCP server executes the requested tools and returns results.
+
+### Step 5: Response
+
+Results are formatted and returned to the user through the router.
+
+## Configuration Management
+
+### MCP Registry (`packages/mcp/mcps.json`)
+
+Central configuration file defining all available MCPs:
+
+```json
+{
+  "mcp-name": {
+    "client": {
+      "command": "npx",
+      "args": ["-y", "@kasarlabs/mcp-name-mcp"],
+      "transport": "stdio",
+      "env": {
+        "REQUIRED_VAR": "",
+        "OPTIONAL_VAR": ""
+      }
+    },
+    "description": "What this MCP does",
+    "promptInfo": {
+      "expertise": "Domain expertise description",
+      "tools": ["tool_name_1", "tool_name_2"]
+    }
+  }
+}
+```
+
+### Dynamic Environment Loading
+
+The router automatically:
+
+1. Loads all environment variables from the host
+2. Validates required variables for each MCP
+3. Passes only necessary variables to each specialized MCP
+
+```typescript
+// From utilities.ts
+export const getMCPClientConfig = (serverName, env) => {
+  const serverInfo = getMcpInfo(serverName);
+  const config = { ...serverInfo.client };
+
+  // Inject environment variables
+  for (const envVar in serverInfo.client.env) {
+    if (env[envVar]) {
+      config.env[envVar] = env[envVar];
+    } else {
+      throw new Error(`Missing: ${envVar}`);
+    }
+  }
+
+  return config;
+};
+```
+
+## State Management
+
+Uses LangGraph's state annotation for type-safe state management:
+
+```typescript
+export const GraphAnnotation = Annotation.Root({
+  messages: Annotation<BaseMessage[]>({
+    reducer: messagesStateReducer,
+    default: () => [],
+  }),
+  next: Annotation<AgentName>({
+    reducer: (x, y) => y ?? x,
+    default: () => END,
+  }),
+  mcpEnvironment: Annotation<MCPEnvironment>({
+    reducer: (x, y) => y ?? x,
+  }),
+  routingInfo: Annotation<{
+    reasoning?: string;
+    timestamp?: string;
+  }>({
+    reducer: (x, y) => ({ ...x, ...y }),
+    default: () => ({}),
+  }),
+});
+```
+
+## Error Handling
+
+### Router Level
+
+- Validates LLM API keys on startup
+- Catches graph execution errors
+- Returns structured error responses
+
+### Specialized MCP Level
+
+- Validates environment variables before initialization
+- Handles tool execution errors
+- Returns error status in consistent format
+
+### Tool Level
+
+- Input validation with Zod schemas
+- Try-catch error handling
+- Detailed error messages
+
+## Extensibility
+
+### Adding New MCPs
+
+1. **Create the MCP server** following the standard structure
+2. **Register in `mcps.json`** with configuration
+3. **Update generated types** with `pnpm generate:mcps-data`
+4. **Build and publish** the package
+
+The router will automatically:
+
+- Discover the new MCP
+- Include it in routing decisions
+- Load required environment variables
+- Make tools available to users
+
+## Performance Considerations
+
+- **Lazy Loading:** MCPs are only loaded when needed
+- **Caching:** LLM responses can be cached for repeated queries
+- **Parallel Execution:** Independent operations can run in parallel
+- **Token Optimization:** Minimal context sent to LLMs
+
+## Security
+
+- **Environment Isolation:** Each MCP only receives necessary env vars
+- **Private Key Protection:** Never logged or exposed
+- **Input Validation:** All inputs validated with Zod schemas
+- **Sandboxed Execution:** MCPs run in isolated stdio processes