Improve documentations

Author: niechen

CONTRIBUTING.md

@@ -3,96 +3,11 @@
 Thank you for considering contributing to mcpm.sh! This document outlines the process for adding or updating MCP servers in the registry.
 
 ## Adding a New Server
-
-1. Fork this repository
-2. Create a new JSON file named after your server under `mcp-registry/servers/` (use kebab-case, e.g., `github.json` or `time-converter.json`)
-3. Ensure your server JSON file adheres to the [server schema](/mcp-registry/schema/server-schema.json)
-
-### Server JSON Requirements
-
-Your server JSON file must include the following required fields:
-
-```json
-{
-  "name": "your-server-name",
-  "display_name": "Your Server Display Name",
-  "description": "Brief description of the server's functionality",
-  "repository": {
-    "type": "git",
-    "url": "https://github.com/your-username/your-repo"
-  },
-  "author": {
-    "name": "Your Name"
-  },
-  "license": "MIT",
-  "categories": ["category1", "category2"],
-  "tags": ["tag1", "tag2"],
-  "arguments": {
-    "EXAMPLE_ARG": {
-      "description": "Description of this argument",
-      "required": false
-    }
-  },
-  "installations": {
-    "npm": {
-      "type": "npm",
-      "command": "npx",
-      "args": ["your-server-package"],
-      "env": {
-        "EXAMPLE_ARG": "${EXAMPLE_ARG}"
-      }
-    }
-  },
-  "examples": [
-    {
-      "title": "Example usage",
-      "description": "Brief description of example",
-      "prompt": "Example prompt to demonstrate server functionality"
-    }
-  ]
-}
-```
-
-For a complete reference of all available fields, see the [server schema](/mcp-registry/schema/server-schema.json).
-
-## Schema Validation
-
-All server JSON files are automatically validated against the schema during the CI process. You can also validate your server JSON locally using the prepare.py script:
-
-```bash
-# From the repository root
-python scripts/prepare.py mcp-registry pages --validate-only
-```
-
-## Updating an Existing Server
-
-1. Fork this repository
-2. Update the relevant server JSON file in the `mcp-registry/servers/` directory
-3. Submit a pull request with a clear description of your changes
+Please follow the instructions in the [mcp-registry/README.md](mcp-registry/README.md) file.
 
 ## Website Development
 
-If you want to contribute to the mcpm.sh website itself:
-
-1. Fork and clone the repository
-2. Run the development server:
-
-```bash
-./dev.sh
-```
-
-3. Access the site at http://localhost:4000
-4. Make your changes to the files in the `pages/` directory
-5. Submit a pull request with a clear description of your changes
-
-## Design Guidelines
-
-mcpm.sh follows a minimal, clean design philosophy:
-
-- Stick to a minimal black and white color scheme
-- Focus on functionality and readability
-- Follow modern web design patterns
-- Keep UI elements simple and focused on content
+Please follow the instructions in the [docs/dev_guide.md](docs/dev_guide.md) file.
 
 ## Code of Conduct
 

README.md

@@ -16,7 +16,7 @@ Built with ❤️ by Path Integral Institute
 
 # 🌟 MCPM - Model Context Protocol Manager
 
-MCPM is a Homebrew-like service and command-line interface for managing Model Context Protocol (MCP) servers. It simplifies managing server configurations across various supported clients, allows grouping servers into profiles, and helps discover new servers via a registry.
+MCPM is a Homebrew-like service and command-line interface for managing Model Context Protocol (MCP) servers. It simplifies managing server configurations across various supported clients, allows grouping servers into profiles, helps discover new servers via a registry, and includes a powerful router that aggregates multiple MCP servers behind a single endpoint with shared sessions.
 
 ## 🤝 Community Contributions
 
@@ -57,9 +57,10 @@ MCPM simplifies the installation, configuration, and management of Model Context
 - ✨ Easy addition and removal of MCP server configurations for supported clients.
 - 📋 Centralized management using profiles: group server configurations together and activate/deactivate them easily.
 - 🔍 Discovery of available MCP servers through a central registry.
-- 🖥️ Detection of installed MCP clients on your system.
+- 🔌 MCPM Router for aggregating multiple MCP servers behind a single endpoint with shared sessions.
 - 💻 A command-line interface (CLI) for all management tasks.
-- 🔧 Utilities like a configuration inspector.
+
+See [Advanced Features](docs/advanced_features.md) for more capabilities like shared server sessions and the MCPM Router.
 
 ## 🖥️ Supported MCP Clients
 
@@ -143,7 +144,9 @@ The MCPM Router runs as a background daemon process, acting as a stable endpoint
 
 This allows you to change the underlying servers (by switching profiles with `mcpm activate`) without reconfiguring your client applications. They can always point to the MCPM Router's address.
 
-For more technical details on the router's implementation and namespacing, see [`src/mcpm/router/README.md`](src/mcpm/router/README.md).
+The Router also maintains persistent connections to MCP servers, enabling multiple clients to share these server sessions. This eliminates the need to start separate server instances for each client, significantly reducing resource usage and startup time. Learn more about these advanced capabilities in [Advanced Features](docs/advanced_features.md).
+
+For more technical details on the router's implementation and namespacing, see [`docs/router_tech_design.md`](docs/router_tech_design.md).
 
 ```bash
 mcpm router status                # Check if the router daemon is running

docs/advanced_features.md

@@ -0,0 +1,114 @@
+# MCPM Router
+
+The MCPM Router is a module that allows you to aggregate multiple MCP servers (both SSE and STDIO) and expose them as a single SSE server. The router acts in a dual role:
+
+1. **As an MCP Client**: Connects to multiple downstream MCP servers
+2. **As an MCP Server**: Provides a unified interface to upstream MCP clients
+
+This design allows for aggregation of capabilities from multiple MCP servers while providing a single, stable connection point for clients. The router also supports profile management to control which servers are available to specific clients.
+
+A key benefit of the MCPM Router is that it maintains persistent connections to MCP servers, allowing multiple clients to share these server sessions. This eliminates the need to start separate server instances for each client, significantly reducing resource usage and startup time.
+
+## How It Works
+
+The MCPM Router sits between your clients and multiple MCP servers, acting as a central hub:
+
+```mermaid
+flowchart TD
+    %% Clients
+    client1[Claude Desktop<br>Profile: Study]
+    client2[Cursor<br>Profile: Development]
+    client3[Goose<br>Profile: Creativity]
+    
+    %% Router with profiles inside
+    subgraph router[MCPM Router]
+        subgraph profiles[Profiles]
+            studyProfile[Study Profile]
+            devProfile[Development Profile]
+            creativeProfile[Creativity Profile]
+        end
+    end
+    
+    %% Servers - concrete examples
+    server1[Notion MCP Server]
+    server2[Python Interpreter MCP Server]
+    server3[Image Generation MCP Server]
+    server4[Web Search MCP Server]
+    server5[Web Fetch MCP Server]
+    server6[Blender MCP Server]
+    server7[Slack MCP Server]
+    
+    %% Client to profile connections directly
+    client1 --> studyProfile
+    client2 --> devProfile
+    client3 --> creativeProfile
+    
+    %% Profile to server access
+    studyProfile --> server1
+    studyProfile --> server4
+    studyProfile --> server5
+    
+    devProfile --> server1
+    devProfile --> server2
+    devProfile --> server4
+    devProfile --> server5
+    devProfile --> server7
+    
+    creativeProfile --> server1
+    creativeProfile --> server3
+    creativeProfile --> server6
+    
+    %% Styling
+    classDef client fill:#d4f1f9,stroke:#333,stroke-width:1px;
+    classDef router fill:#ffcc99,stroke:#333,stroke-width:1px;
+    classDef server fill:#d5e8d4,stroke:#333,stroke-width:1px;
+    classDef profile fill:#e1d5e7,stroke:#333,stroke-width:1px;
+    
+    class client1,client2,client3 client;
+    class router router;
+    class server1,server2,server3,server4,server5,server6,server7 server;
+    class studyProfile,devProfile,creativeProfile,profiles profile;
+```
+
+### Key Concepts
+
+#### 1. Unified Access
+Clients connect only to the router, not directly to servers. The router provides a single endpoint for accessing capabilities from all connected servers.
+
+#### 2. Profiles
+Profiles are configurations within the router that determine which servers' capabilities are exposed to each client:
+
+| Client         | Profile     | Available Servers                                        |
+| -------------- | ----------- | -------------------------------------------------------- |
+| Claude Desktop | Study       | Notion, Web Search, Web Fetch                            |
+| Cursor         | Development | Notion, Python Interpreter, Web Search, Web Fetch, Slack |
+| Goose          | Creativity  | Notion, Image Generation, Blender                        |
+
+#### 3. Namespacing
+The router prefixes capabilities from different servers to avoid conflicts:
+- Tools: `notion_t_pageSearch` or `python_t_executeCode`
+- Prompts: `image_p_generatePortrait`
+- Resources: `webfetch:https://example.com`
+
+#### 4. Server Connections
+The router supports both STDIO (command-line) and SSE (HTTP) server connections. For example:
+- STDIO: Python Interpreter, Blender
+- SSE: Web Search, Notion, Slack
+
+#### 5. Shared Server Sessions
+The router maintains persistent connections to all configured servers, allowing multiple clients to share the same server sessions. This means:
+- Only one instance of each server is needed regardless of client count
+- Server initialization happens only once
+- State can be shared across clients when appropriate
+- Resources like memory and CPU usage are significantly reduced
+
+## Features
+
+- Aggregate multiple MCP servers as a single server
+- Support both SSE and STDIO connections to underlying servers
+- Namespace capabilities from different servers
+- Expose a unified SSE server interface
+- Profile-based server access control
+- Dynamic configuration reloading
+- Share server connections among multiple clients (no need for separate server instances per client)
+- Reduce resource usage through connection pooling