pse-mcp 0.1.0

package/MCP Documents/mcp-enhanced-instructions.md

@@ -0,0 +1,297 @@
+# Instructions for LLM:
+
+You are an expert software development assistant. Your task is to provide a detailed plan and guidance for building a Windows desktop application according to the user's requirements.
+
+## User Goal:
+Create a Windows desktop application that allows a user to have a text-based conversation with Google's Gemini Flash 2.0 model via the Google Gemini API, while also supporting Anthropic's Model Context Protocol (MCP) for enhanced contextual capabilities. The application should support requests for image generation from Gemini and allow the user to save the generated images locally, preferably in the chat window as part of the conversation.
+
+## Core Requirements:
+
+- **Platform**: Windows Desktop.
+
+- **Functionality**:
+  - Chat interface for conversation with Gemini Flash 2.0.
+  - Integration with Anthropic's Model Context Protocol (MCP) for accessing external data sources and tools.
+  - Ability to request image generation within the conversation.
+  - Display generated images within the application.
+  - Save generated images to the user's local machine.
+
+- **APIs**: 
+  - Google Gemini API for text and image generation
+  - Model Context Protocol (MCP) support for connecting to data sources and tools
+
+- **Models**: 
+  - Gemini Flash 2.0 (or latest appropriate Flash model).
+  - Support for MCP-compatible models
+
+- **Technology**: User suggested Node.js, React, Three.js but is open. We will recommend Electron with Node.js and potentially React for the UI, as this fits the desktop requirement and leverages JavaScript expertise.
+
+## Recommended Technology Stack:
+
+- **Framework**: Electron (Allows building cross-platform desktop apps with web technologies - HTML, CSS, JavaScript).
+
+- **Backend Logic (Main Process)**: Node.js (Runs within Electron's main process, handles API calls, file system operations). 
+
+- **Frontend UI (Renderer Process)**: HTML, CSS, JavaScript. Optionally, use React for building the user interface components, as suggested by the user and well-supported within Electron. 
+
+- **API Interactions**:
+  - Official Google Generative AI SDK for JavaScript (@google/generative-ai)
+  - Model Context Protocol SDKs (@anthropic/mcp-sdk or official TypeScript/JavaScript SDK)
+
+## Detailed Plan & Steps:
+
+### Phase 1: Setup and Basic Structure
+
+#### Environment Setup:
+
+- Ensure Node.js and npm (or yarn) are installed.
+- Obtain a Google Gemini API Key from Google AI Studio. Store this key securely.
+- If using Anthropic's Claude models via MCP, obtain necessary API credentials.
+
+#### Project Initialization:
+
+- Create a new project directory.
+- Initialize npm: `npm init -y`
+- Install Electron: `npm install --save-dev electron`
+- Optional (If using React): Use a template like electron-vite with React or manually set up create-react-app and integrate it with Electron. Install React dependencies: `npm install react react-dom`.
+- Install the Google AI SDK: `npm install @google/generative-ai`
+- Install the MCP SDK: `npm install @anthropic/mcp-client` (or official MCP TypeScript SDK)
+- Install dotenv for API key management: `npm install dotenv`
+
+#### Electron Basic Structure:
+
+- Create the main process entry file (e.g., main.js or src/electron/main.js). This Node.js script creates the application window (BrowserWindow) and handles system events.
+- Create the renderer process files (e.g., index.html, renderer.js, style.css or React components if using React). This is the web page displayed within the Electron window.
+- Configure package.json: Set the main field to your main process file and add a script to start Electron (e.g., "start": "electron .").
+- Establish Inter-Process Communication (IPC) using ipcMain (in main.js) and ipcRenderer (in renderer.js or React components) for communication between the frontend and backend.
+
+### Phase 2: UI Development
+
+#### Design the UI (Renderer Process):
+
+- Create the chat interface layout using HTML and CSS (or React components).
+- Include:
+  - A display area for chat messages (user, Gemini, and MCP-enhanced responses).
+  - An input field for the user to type messages.
+  - A "Send" button.
+  - A tool/context selector for choosing between Gemini and MCP servers.
+  - An area to display generated images.
+  - A "Save Image" button (initially hidden or disabled).
+
+### Phase 3: MCP Integration
+
+#### Setup MCP Client:
+
+- In the main process, create MCP client initialization logic:
+```javascript
+const { createClient } = require('@anthropic/mcp-client'); // or equivalent SDK
+
+// Initialize MCP client
+const mcpClient = createClient({
+  // Configure with appropriate options
+});
+```
+
+#### Implement MCP Server Discovery & Connections:
+
+- Create a mechanism to discover and connect to local MCP servers.
+- Implement a configuration system to store MCP server settings:
+```javascript
+// Example MCP server configuration in settings.json
+const mcpServerConfig = {
+  "fileSystem": {
+    "command": "node",
+    "args": ["./mcp-servers/filesystem-server.js"]
+  },
+  "database": {
+    "command": "node",
+    "args": ["./mcp-servers/database-server.js"]
+  }
+};
+```
+
+#### Create Process Management for MCP Servers:
+
+- Implement a system to start/stop MCP server processes.
+- Handle IPC messages to manage these servers from the UI.
+
+#### Implement MCP Tool Calls:
+
+- Create a mechanism for sending tool requests to MCP servers.
+- Handle responses and integrate them into the chat flow.
+```javascript
+async function callMCPTool(serverName, toolName, params) {
+  const server = mcpClient.connectToServer(serverName);
+  const toolResponse = await server.callTool(toolName, params);
+  return toolResponse;
+}
+```
+
+### Phase 4: Gemini API Integration (Text)
+
+#### Setup Gemini Client (Main Process):
+
+- In main.js, import and initialize the @google/generative-ai SDK using your API key (loaded securely via dotenv).
+- Specify the gemini-1.5-flash-latest model (or check documentation for the exact identifier for Gemini Flash 2.0 when available).
+
+#### Implement Text Chat Logic:
+
+- Renderer: When the user clicks "Send", capture the input text and send it to the main process via IPC (e.g., ipcRenderer.send('send-message', userText)).
+- Main Process: Set up an ipcMain.on('send-message', ...) listener.
+- Inside the listener:
+  - Determine whether to use Gemini API directly or route through MCP based on user selection/context.
+  - For Gemini direct use: Call the Gemini API using the SDK's generateContent method with the user's text prompt.
+  - For MCP-enhanced use: Transform the Gemini "tool calling" format to MCP format and use appropriate MCP servers.
+  - Handle the asynchronous response.
+  - Send the response back to the renderer process via IPC.
+- Renderer: Display the received response in the chat display area.
+
+### Phase 5: Bridge Gemini Tool Calling with MCP
+
+#### Create MCP-to-Gemini Adapter:
+
+- Implement a mechanism to translate between Gemini's tool calling format and MCP's protocol:
+```javascript
+function adaptGeminiToolCallToMCP(geminiToolCall) {
+  // Transform Gemini tool call format to MCP format
+  const mcpToolCall = {
+    name: geminiToolCall.name,
+    parameters: geminiToolCall.parameters
+    // Add other necessary MCP fields
+  };
+  return mcpToolCall;
+}
+
+function adaptMCPResponseToGemini(mcpResponse) {
+  // Transform MCP response format to Gemini format
+  const geminiResponse = {
+    // Format appropriately for Gemini
+  };
+  return geminiResponse;
+}
+```
+
+### Phase 6: Gemini API Integration (Image Generation)
+
+#### Implement Image Generation Request:
+
+- Determine Trigger: Decide how the user requests an image (e.g., specific keywords in the prompt like "generate an image of...", a separate button, etc.).
+- Renderer: When an image request is detected, send the prompt to the main process via IPC.
+- Main Process: Handle image generation requests.
+- Call the Gemini API using the SDK. Check the Gemini API documentation for the exact model and parameters needed for image generation.
+
+#### Process Image Response (Main Process):
+
+- Extract the image data (Base64, URL, etc.) based on the response format.
+- If it returns a URL, use Node.js's built-in fetch or libraries like axios to download the image data.
+
+#### Display Image (Renderer Process):
+
+- Main Process: Send the image data back to the renderer process via IPC.
+- Renderer: Display the image in the designated image display area.
+- Enable the "Save Image" button.
+
+### Phase 7: Image Saving
+
+#### Implement Image Saving:
+
+- Renderer: Add an event listener to the "Save Image" button. When clicked, send a request to the main process via IPC.
+- Main Process: Set up an IPC listener for save requests.
+- Use Electron's dialog.showSaveDialog method to prompt the user for a file path and name.
+- Save the image data to the selected file path.
+- Optionally, send a confirmation or error message back to the renderer.
+
+### Phase 8: MCP Server Implementation Examples
+
+#### Implement Example MCP Servers:
+
+- Create a directory for MCP server implementations.
+- Implement basic servers for common use cases:
+
+1. **File System MCP Server**:
+```javascript
+const { Server, Tool } = require('@anthropic/mcp-server'); // or equivalent SDK
+
+const app = new Server("filesystem-server");
+
+// List tools
+app.listTools(() => [
+  new Tool({
+    name: "read_file",
+    description: "Read content from a file",
+    inputSchema: {
+      type: "object",
+      properties: {
+        path: { type: "string", description: "Path to the file" }
+      },
+      required: ["path"]
+    }
+  }),
+  new Tool({
+    name: "write_file",
+    description: "Write content to a file",
+    inputSchema: {
+      type: "object",
+      properties: {
+        path: { type: "string", description: "Path to the file" },
+        content: { type: "string", description: "Content to write" }
+      },
+      required: ["path", "content"]
+    }
+  })
+]);
+
+// Implement tool handlers
+app.handleTool("read_file", async ({ path }) => {
+  const fs = require('fs').promises;
+  const content = await fs.readFile(path, 'utf-8');
+  return { content };
+});
+
+app.handleTool("write_file", async ({ path, content }) => {
+  const fs = require('fs').promises;
+  await fs.writeFile(path, content, 'utf-8');
+  return { success: true };
+});
+
+// Start the server
+app.start();
+```
+
+2. **Database MCP Server**:
+```javascript
+// Similar structure for database access
+```
+
+### Phase 9: Refinement and Packaging
+
+#### Error Handling:
+- Implement robust error handling for API calls, MCP interactions, file operations, and IPC communication.
+
+#### Packaging:
+- Use tools like electron-builder or electron-packager to bundle the application into a distributable Windows executable (.exe).
+- Configure package.json with necessary build settings (app ID, icons, etc.).
+
+## Important Considerations:
+
+### API Key Security:
+- The Gemini API key and any Anthropic API credentials must be kept secure and not embedded directly in client-side/renderer code. Use environment variables loaded in the main process.
+
+### Gemini-MCP Interoperability:
+- Gemini and MCP use different formats for tool calling. Create adapters to translate between these formats.
+- Document clearly how the two systems interact within your application.
+
+### MCP Server Management:
+- MCP servers typically run as separate processes. Implement proper process management to start/stop these servers as needed.
+- Consider resource usage and ensure servers are properly terminated when the application closes.
+
+### Asynchronous Operations:
+- Most operations (API calls, MCP interactions, file I/O, IPC) are asynchronous. Use async/await or Promises correctly.
+
+### Rate Limits:
+- Be mindful of Gemini API usage limits and costs.
+- Implement appropriate rate limiting for MCP server calls.
+
+### Documentation:
+- Provide clear documentation on how to configure and use MCP servers within your application.
+- Explain the differences between using Gemini directly vs. through MCP.

package/MCP Documents/mcp-server-guide.md

@@ -0,0 +1,415 @@
+# Guide for Building an MCP Server
+
+## Introduction to MCP Servers
+
+A Model Context Protocol (MCP) server is a component that exposes data, tools, and prompts to LLM applications in a standardized way. Think of it as an API specifically designed for LLM interactions.
+
+MCP servers can:
+- Expose data through **Resources** (providing context to LLMs)
+- Provide functionality through **Tools** (executable functions)
+- Define interaction patterns through **Prompts** (reusable templates for LLM interactions)
+
+## Prerequisites
+
+- Node.js (version 18 or later) and npm
+- Basic knowledge of TypeScript/JavaScript or Python
+- VS Code (recommended for development)
+
+## Getting Started with TypeScript Implementation
+
+### 1. Setting Up Your Project
+
+Create a new directory for your MCP server:
+
+```bash
+mkdir my-mcp-server
+cd my-mcp-server
+npm init -y
+```
+
+Install the MCP SDK:
+
+```bash
+npm install @modelcontextprotocol/sdk
+```
+
+Add TypeScript and other dev dependencies:
+
+```bash
+npm install --save-dev typescript ts-node @types/node
+```
+
+Create a `tsconfig.json` file:
+
+```json
+{
+  "compilerOptions": {
+    "target": "ES2020",
+    "module": "NodeNext",
+    "esModuleInterop": true,
+    "forceConsistentCasingInFileNames": true,
+    "strict": true,
+    "skipLibCheck": true,
+    "outDir": "./build"
+  },
+  "include": ["src/**/*"]
+}
+```
+
+### 2. Creating Your Server
+
+Create a `src` directory and an `index.ts` file inside it:
+
+```bash
+mkdir src
+touch src/index.ts
+```
+
+### 3. Basic Server Implementation
+
+Here's a basic MCP server implementation:
+
+```typescript
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { z } from "@modelcontextprotocol/sdk/deps.js";
+
+// Create a new MCP server
+const server = new McpServer({
+  name: "example-server",
+  version: "1.0.0",
+});
+
+// Define a resource
+server.resource(
+  "greeting",
+  {},
+  async () => {
+    return {
+      content: {
+        type: "text",
+        text: "Hello from MCP server!",
+      },
+    };
+  }
+);
+
+// Define a tool
+server.tool(
+  "echo",
+  {
+    message: z.string().describe("Message to echo"),
+  },
+  async ({ message }) => {
+    return {
+      content: {
+        type: "text",
+        text: `You said: ${message}`,
+      },
+    };
+  }
+);
+
+// Define a prompt
+server.prompt(
+  "introduce",
+  {
+    name: z.string().describe("Person's name"),
+  },
+  ({ name }) => ({
+    messages: [
+      {
+        role: "user",
+        content: {
+          type: "text",
+          text: `Please introduce yourself to ${name}.`,
+        },
+      },
+    ],
+  })
+);
+
+// Start the server
+const transport = new StdioServerTransport();
+server.listen(transport);
+```
+
+### 4. Building and Running
+
+Add scripts to your `package.json`:
+
+```json
+"scripts": {
+  "build": "tsc",
+  "start": "node build/index.js"
+}
+```
+
+Build and run your server:
+
+```bash
+npm run build
+npm run start
+```
+
+## Getting Started with Python Implementation
+
+### 1. Setting Up Your Python Environment
+
+```bash
+# Create and activate a virtual environment
+python -m venv venv
+source venv/bin/activate  # On Windows: venv\Scripts\activate
+
+# Install the MCP SDK
+pip install mcp-sdk
+```
+
+### 2. Creating a Basic Python MCP Server
+
+Create a file named `server.py`:
+
+```python
+import asyncio
+from mcp import Server, StdioTransport, Tool, Resource, Prompt
+from pydantic import BaseModel
+
+class EchoParams(BaseModel):
+    message: str
+
+class GreetingParams(BaseModel):
+    name: str
+
+# Create a server
+server = Server(name="python-example-server", version="1.0.0")
+
+# Define a resource
+@server.resource("greeting")
+async def greeting_resource(params=None):
+    return {
+        "content": {
+            "type": "text",
+            "text": "Hello from Python MCP server!"
+        }
+    }
+
+# Define a tool
+@server.tool("echo")
+async def echo_tool(params: EchoParams):
+    return {
+        "content": {
+            "type": "text",
+            "text": f"You said: {params.message}"
+        }
+    }
+
+# Define a prompt
+@server.prompt("introduce")
+async def introduce_prompt(params: GreetingParams):
+    return {
+        "messages": [
+            {
+                "role": "user",
+                "content": {
+                    "type": "text",
+                    "text": f"Please introduce yourself to {params.name}."
+                }
+            }
+        ]
+    }
+
+# Run the server
+if __name__ == "__main__":
+    transport = StdioTransport()
+    asyncio.run(server.listen(transport))
+```
+
+Run your Python server:
+
+```bash
+python server.py
+```
+
+## Advanced MCP Server Concepts
+
+### 1. Adding Authentication
+
+For HTTP transport, you might need to add authentication:
+
+```typescript
+// TypeScript example
+import { HttpServerTransport } from "@modelcontextprotocol/sdk/server/http.js";
+
+const transport = new HttpServerTransport({
+  port: 3000,
+  auth: async (req) => {
+    const token = req.headers.authorization?.split(" ")[1];
+    if (token !== "your-secret-token") {
+      throw new Error("Unauthorized");
+    }
+  },
+});
+```
+
+### 2. Working with External APIs
+
+MCP servers often connect to external services:
+
+```typescript
+// TypeScript example with an external API
+import fetch from "node-fetch";
+
+server.tool(
+  "get-weather",
+  {
+    location: z.string().describe("Location to get weather for"),
+  },
+  async ({ location }) => {
+    try {
+      const response = await fetch(
+        `https://api.weatherapi.com/v1/current.json?key=YOUR_API_KEY&q=${location}`
+      );
+      const data = await response.json();
+      
+      return {
+        content: {
+          type: "text",
+          text: `Current weather in ${location}: ${data.current.temp_c}°C, ${data.current.condition.text}`,
+        },
+      };
+    } catch (error) {
+      return {
+        content: {
+          type: "text",
+          text: `Error fetching weather data: ${error.message}`,
+        },
+      };
+    }
+  }
+);
+```
+
+### 3. Dynamic Resources
+
+Resources can dynamically generate content based on parameters:
+
+```typescript
+server.resource(
+  "document",
+  {
+    id: z.string().describe("Document ID to retrieve"),
+  },
+  async ({ id }) => {
+    // Imagine this fetches from a database
+    const document = await getDocumentById(id);
+    
+    return {
+      content: {
+        type: "text",
+        text: document.content,
+      },
+    };
+  }
+);
+```
+
+## Best Practices
+
+1. **Keep it Simple**: Start with basic capabilities and expand gradually.
+2. **Error Handling**: Always include proper error handling in your tools and resources.
+3. **Validation**: Use Zod (TypeScript) or Pydantic (Python) for robust parameter validation.
+4. **Documentation**: Provide clear descriptions for all tools, resources, and prompts.
+5. **Security**: Be cautious about what your server exposes, especially with tools that execute code.
+6. **Testing**: Test your MCP server with real clients like Claude Desktop or Cody.
+7. **Platform Compatibility**: 
+   - Test on both Unix and Windows systems
+   - Use binary mode for stdio on Windows
+   - Handle path separators correctly
+   - Consider using cross-platform libraries
+8. **Resource Management**:
+   - Implement proper cleanup for resources
+   - Handle connection timeouts gracefully
+   - Monitor memory usage
+   - Cache responses when appropriate
+9. **Versioning**:
+   - Follow semantic versioning
+   - Maintain backwards compatibility
+   - Document breaking changes
+   - Provide migration guides
+
+## Platform-Specific Considerations
+
+### Windows Implementation
+When developing MCP servers for Windows:
+
+1. **stdio Handling**:
+```typescript
+if (process.platform === 'win32') {
+    process.stdin.setEncoding('binary');
+    process.stdout.setDefaultEncoding('binary');
+}
+```
+
+2. **Path Management**:
+```typescript
+import { join } from 'path';
+
+const configPath = join(process.cwd(), 'config.json');
+```
+
+3. **Error Handling**:
+```typescript
+process.on('uncaughtException', (error) => {
+    console.error(`Uncaught Exception: ${error.message}`);
+    process.exit(1);
+});
+```
+
+### Unix Implementation
+For Unix-based systems:
+
+1. **Signal Handling**:
+```typescript
+process.on('SIGTERM', () => {
+    console.error('Received SIGTERM, shutting down...');
+    process.exit(0);
+});
+```
+
+2. **File Permissions**:
+```typescript
+import { chmod } from 'fs/promises';
+
+await chmod('server.sh', 0o755);
+```
+
+## Integration with VS Code
+
+If you're developing an MCP server for VS Code:
+
+1. Follow the standard MCP server implementation.
+2. Consider using the VS Code Extension API for deeper integration.
+3. Look at examples like Continue, Cody, or other VS Code extensions that implement MCP.
+4. Handle workspace-specific configurations.
+5. Implement proper error reporting to VS Code's output channels.
+
+## Debugging
+
+For debugging your MCP server:
+
+1. Use console logs to track execution flow.
+2. Implement detailed error messages.
+3. Use VS Code's debugging features for TypeScript/JavaScript or Python.
+4. Test with simple clients first before integrating with more complex systems.
+
+## Resources
+
+- [Official MCP Documentation](https://modelcontextprotocol.io/)
+- [MCP Specification](https://spec.modelcontextprotocol.io/)
+- [TypeScript SDK GitHub Repository](https://github.com/modelcontextprotocol/typescript-sdk)
+- [Python SDK GitHub Repository](https://github.com/modelcontextprotocol/python-sdk)
+- [Example MCP Servers Repository](https://github.com/modelcontextprotocol/servers)
+
+---
+
+This guide provides a foundation for building MCP servers. As the ecosystem evolves, new patterns and best practices will emerge. Stay updated with the official documentation and community resources for the latest developments.