MCP Server Development Protocol

# MCP Server Development Protocol

⚠️ CRITICAL: DO NOT USE attempt_completion BEFORE TESTING ⚠️

## Step 1: Planning (PLAN MODE)

-   What problem does this tool solve?
-   What API/service will it use?
-   What are the authentication requirements?
    □ Standard API key
    □ OAuth (requires separate setup script)
    □ Other credentials

## Step 2: Implementation (ACT MODE)

1. Bootstrap

    - For web services, JavaScript integration, or Node.js environments:
        ```bash
        npx @modelcontextprotocol/create-server my-server
        cd my-server
        npm install
        ```
    - For data science, ML workflows, or Python environments:
        ```bash
        pip install mcp
        # Or with uv (recommended)
        uv add "mcp[cli]"
        ```

2. Core Implementation

    - Use MCP SDK
    - Implement comprehensive logging
        - TypeScript (for web/JS projects):
            ```typescript
            console.error("[Setup] Initializing server...")
            console.error("[API] Request to endpoint:", endpoint)
            console.error("[Error] Failed with:", error)
            ```
        - Python (for data science/ML projects):
            ```python
            import logging
            logging.error('[Setup] Initializing server...')
            logging.error(f'[API] Request to endpoint: {endpoint}')
            logging.error(f'[Error] Failed with: {str(error)}')
            ```
    - Add type definitions
    - Handle errors with context
    - Implement rate limiting if needed

3. Configuration

    - Get credentials from user if needed
    - Add to MCP settings:

        - For TypeScript projects:
            ```json
            {
            	"mcpServers": {
            		"my-server": {
            			"command": "node",
            			"args": ["path/to/build/index.js"],
            			"env": {
            				"API_KEY": "key"
            			},
            			"disabled": false,
            			"autoApprove": []
            		}
            	}
            }
            ```
        - For Python projects:

            ```bash
            # Directly with command line
            mcp install server.py -v API_KEY=key

            # Or in settings.json
            {
              "mcpServers": {
                "my-server": {
                  "command": "python",
                  "args": ["server.py"],
                  "env": {
                    "API_KEY": "key"
                  },
                  "disabled": false,
                  "autoApprove": []
                }
              }
            }
            ```

## Step 3: Testing (BLOCKER ⛔️)

<thinking>
BEFORE using attempt_completion, I MUST verify:
□ Have I tested EVERY tool?
□ Have I confirmed success from the user for each test?
□ Have I documented the test results?

If ANY answer is "no", I MUST NOT use attempt_completion.
</thinking>

1. Test Each Tool (REQUIRED)
   □ Test each tool with valid inputs
   □ Verify output format is correct
   ⚠️ DO NOT PROCEED UNTIL ALL TOOLS TESTED

## Step 4: Completion

❗ STOP AND VERIFY:
□ Every tool has been tested with valid inputs
□ Output format is correct for each tool

Only after ALL tools have been tested can attempt_completion be used.

## Key Requirements

-   ✓ Must use MCP SDK
-   ✓ Must have comprehensive logging
-   ✓ Must test each tool individually
-   ✓ Must handle errors gracefully
-   ⛔️ NEVER skip testing before completion

I want to build an MCP server for the AlphaAdvantage financial API.
It should allow me to get real-time stock data, perform technical
analysis, and retrieve company financial information.

Here's the API documentation for the service:
[Paste API documentation here]

npx @modelcontextprotocol/create-server alphaadvantage-mcp
cd alphaadvantage-mcp
npm install axios node-cache

src/
  ├── api/
  │   └── alphaAdvantageClient.ts  # API client with rate limiting & caching
  ├── formatters/
  │   └── markdownFormatter.ts     # Output formatters for clean markdown
  └── index.ts                     # Main MCP server implementation

/**
 * Manage rate limiting based on free tier (5 calls per minute)
 */
private async enforceRateLimit() {
  if (this.requestsThisMinute >= 5) {
    console.error("[Rate Limit] Rate limit reached. Waiting for next minute...");
    return new Promise<void>((resolve) => {
      const remainingMs = 60 * 1000 - (Date.now() % (60 * 1000));
      setTimeout(resolve, remainingMs + 100); // Add 100ms buffer
    });
  }

  this.requestsThisMinute++;
  return Promise.resolve();
}

/**
 * Format company overview into markdown
 */
export function formatStockOverview(overviewData: any, quoteData: any): string {
	// Extract data
	const overview = overviewData
	const quote = quoteData["Global Quote"]

	// Calculate price change
	const currentPrice = parseFloat(quote["05. price"] || "0")
	const priceChange = parseFloat(quote["09. change"] || "0")
	const changePercent = parseFloat(quote["10. change percent"]?.replace("%", "") || "0")

	// Format markdown
	let markdown = `# ${overview.Symbol} (${overview.Name}) - ${formatCurrency(currentPrice)} ${addTrendIndicator(priceChange)}${changePercent > 0 ? "+" : ""}${changePercent.toFixed(2)}%\n\n`

	// Add more details...

	return markdown
}

server.setRequestHandler(ListToolsRequestSchema, async () => {
	console.error("[Setup] Listing available tools")

	return {
		tools: [
			{
				name: "get_stock_overview",
				description: "Get basic company info and current quote for a stock symbol",
				inputSchema: {
					type: "object",
					properties: {
						symbol: {
							type: "string",
							description: "Stock symbol (e.g., 'AAPL')",
						},
						market: {
							type: "string",
							description: "Optional market (e.g., 'US')",
							default: "US",
						},
					},
					required: ["symbol"],
				},
			},
			// Additional tools defined here...
		],
	}
})

{
	"mcpServers": {
		"alphaadvantage-mcp": {
			"command": "node",
			"args": ["/path/to/alphaadvantage-mcp/build/index.js"],
			"env": {
				"ALPHAVANTAGE_API_KEY": "YOUR_API_KEY"
			},
			"disabled": false,
			"autoApprove": []
		}
	}
}

// Start-up logging
console.error("[Setup] Initializing AlphaAdvantage MCP server...")

// API request logging
console.error(`[API] Getting stock overview for ${symbol}`)

// Error handling with context
console.error(`[Error] Tool execution failed: ${error.message}`)

// Cache operations
console.error(`[Cache] Using cached data for: ${cacheKey}`)

export interface AlphaAdvantageConfig {
	apiKey: string
	cacheTTL?: Partial<typeof DEFAULT_CACHE_TTL>
	baseURL?: string
}

/**
 * Validate that a stock symbol is provided and looks valid
 */
function validateSymbol(symbol: unknown): asserts symbol is string {
	if (typeof symbol !== "string" || symbol.trim() === "") {
		throw new McpError(ErrorCode.InvalidParams, "A valid stock symbol is required")
	}

	// Basic symbol validation (letters, numbers, dots)
	const symbolRegex = /^[A-Za-z0-9.]+$/
	if (!symbolRegex.test(symbol)) {
		throw new McpError(ErrorCode.InvalidParams, `Invalid stock symbol: ${symbol}`)
	}
}

// Default cache TTL in seconds
const DEFAULT_CACHE_TTL = {
	STOCK_OVERVIEW: 60 * 60, // 1 hour
	TECHNICAL_ANALYSIS: 60 * 30, // 30 minutes
	FUNDAMENTAL_ANALYSIS: 60 * 60 * 24, // 24 hours
	EARNINGS_REPORT: 60 * 60 * 24, // 24 hours
	NEWS: 60 * 15, // 15 minutes
}

// Check cache first
const cachedData = this.cache.get<T>(cacheKey)
if (cachedData) {
	console.error(`[Cache] Using cached data for: ${cacheKey}`)
	return cachedData
}

// Cache successful responses
this.cache.set(cacheKey, response.data, cacheTTL)

try {
	switch (request.params.name) {
		case "get_stock_overview": {
			// Implementation...
		}

		// Other cases...

		default:
			throw new McpError(ErrorCode.MethodNotFound, `Unknown tool: ${request.params.name}`)
	}
} catch (error) {
	console.error(`[Error] Tool execution failed: ${error instanceof Error ? error.message : String(error)}`)

	if (error instanceof McpError) {
		throw error
	}

	return {
		content: [
			{
				type: "text",
				text: `Error: ${error instanceof Error ? error.message : String(error)}`,
			},
		],
		isError: true,
	}
}

server.setRequestHandler(ListResourcesRequestSchema, async () => {
	return {
		resources: [
			{
				uri: "file:///project/readme.md",
				name: "Project README",
				mimeType: "text/markdown",
			},
		],
	}
})

server.setRequestHandler(ReadResourceRequestSchema, async (request) => {
	if (request.params.uri === "file:///project/readme.md") {
		const content = await fs.promises.readFile("/path/to/readme.md", "utf-8")
		return {
			contents: [
				{
					uri: request.params.uri,
					mimeType: "text/markdown",
					text: content,
				},
			],
		}
	}

	throw new Error("Resource not found")
})

// Authenticate using API key from environment
const API_KEY = process.env.ALPHAVANTAGE_API_KEY
if (!API_KEY) {
	console.error("[Error] Missing ALPHAVANTAGE_API_KEY environment variable")
	process.exit(1)
}

// Initialize API client
const apiClient = new AlphaAdvantageClient({
	apiKey: API_KEY,
})

if (this.requestsThisMinute >= 5) {
	console.error("[Rate Limit] Rate limit reached. Waiting for next minute...")
	return new Promise<void>((resolve) => {
		const remainingMs = 60 * 1000 - (Date.now() % (60 * 1000))
		setTimeout(resolve, remainingMs + 100) // Add 100ms buffer
	})
}