{"id":27876264,"url":"https://github.com/hamidra/yamcp","last_synced_at":"2025-05-05T02:45:29.024Z","repository":{"id":290486488,"uuid":"968918137","full_name":"hamidra/yamcp","owner":"hamidra","description":"Organize your MCP servers in local workspaces.","archived":false,"fork":false,"pushed_at":"2025-04-29T03:57:57.000Z","size":10786,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-04-29T04:42:41.657Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/hamidra.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-04-19T01:37:57.000Z","updated_at":"2025-04-29T04:31:04.000Z","dependencies_parsed_at":"2025-04-29T04:52:48.155Z","dependency_job_id":null,"html_url":"https://github.com/hamidra/yamcp","commit_stats":null,"previous_names":["hamidra/yamcp"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hamidra%2Fyamcp","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hamidra%2Fyamcp/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hamidra%2Fyamcp/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hamidra%2Fyamcp/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/hamidra","download_url":"https://codeload.github.com/hamidra/yamcp/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":252429935,"owners_count":21746570,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-05-05T02:45:27.325Z","updated_at":"2025-05-05T02:45:29.017Z","avatar_url":"https://github.com/hamidra.png","language":"TypeScript","funding_links":[],"categories":["Aggregators \u0026 Gateways","📦 \u003ca name=\"data-platforms\"\u003e\u003c/a\u003eData Platforms","🧑‍🎨 \u003ca name=\"art-literature\"\u003e\u003c/a\u003eArt \u0026 Literature","mcp-server","📦 Other","📚 Projects (2474 total)","Utilities","MCP Servers \u0026 Protocol"],"sub_categories":["Aggregators","Server Managers","MCP Servers","Proxies and Gateways"],"readme":"# 🍠 YAMCP - A Model Context Workspace Manager\n\nYAMCP (YAM-C-P) is a command-line tool for organizing and managing MCP servers as local workspaces. It seamlessly connects to multiple MCP servers, local or remote, grouping them into a unified workspace exposed as Yet Another MCP server (YAM) for AI applications. You can create dedicated workspaces based on specific functionality (e.g., a YAM workspace for coding, design, research, ...) or based on the AI apps that consume servers (e.g., a YAM for Cursor, Claude, Windsurf) or any other combination in between. In addition, it simplifies monitoring and debugging MCP servers by centralizing all server communication logs in a single store, eliminating the need to dig through each AI client app’s logs separately.\n\n## Import and Create Workspaces\n\n\u003cdiv align=\"center\"\u003e\n\u003cimg src=\"assets/demo/yamcp.gif\" alt=\"yamcp demoo\" width=\"700px\"/\u003e\n\u003c/div\u003e\n\n## Connect All Bundled Servers in a Workspace to Your AI Apps with One Config\n\n\u003cdiv align=\"center\"\u003e\n\u003cimg src=\"assets/demo/cursor.gif\" alt=\"cursor demo\" width=\"700px\"/\u003e\n\u003c/div\u003e\n\n## 🚀 Quick Start\n\n```bash\n# Install YAMCP\nnpm install -g yamcp  # or use npx yamcp\n\n# Import servers (choose one)\nyamcp server import [config]    # import servers from config file (see src/example-servers.json for format)\nyamcp server add                # or add manually\n\n# create workspaces (e.g. a yam for coding, design, data, ...)\nyamcp yam create\n\n# Run workspace in your AI app\nyamcp run \u003cyam-workspace-name\u003e\n```\n\n## 🔑 Key Concepts\n\n- **MCP Servers**: Remote or local servers that provide Model Context Protocol services\n- **Workces (YAMs)**: Collections of MCP servers grouped together to be shared with AI Apps (e.g. a workce for coding, writing, design, magic making!)\n- **Gateway**: A local MCP server that manages connections to configured MCP servers in a workce and exposes them through a unified server to AI App's MCP clients\n\nWith YAMCP, you can:\n\n- Create workces to group MCP servers by AI application (e.g. Cursor, Claude, GitHub Copilot)\n- Group servers by workflow purpose (e.g. software development, data science, technical writing)\n- Connect AI apps to a single gateway that provides access to all workce servers\n- Manage and monitor multiple MCP server connections through a unified interface\n- Track all server communications with detailed logging and debugging capabilities\n\n## Top-Level Commands\n\n```bash\nyamcp [command] [subcommand] [flags]\n```\n\nAvailable top-level commands:\n\n- `server` - Manage MCP providers\n- `yam` - Manage workspaces (yams)\n- `run` - Run the gateway with a workspace\n- `log` - View the server log location\n\n---\n\n## 🔧 **Mcp Server Management Commands**\n\n### Server Commands\n\n```bash\nyamcp server add      # Add a new MCP server (interactive)\nyamcp server list     # List all configured servers and their status\nyamcp server remove   # Remove a server configuration\nyamcp server import   # Import server configurations from a JSON file\n```\n\n---\n\n## 🍠 **Yam Workspace Management Commands**\n\n### Workspace Commands\n\n```bash\nyamcp yam create      # Create a new workspace (interactive)\nyamcp yam list        # List all workspaces or show specific workspace details\nyamcp yam edit        # Modify an existing workspace configuration\nyamcp yam scan            # Scan workspaces\nyamcp yam delete          # Delete a workspace\n```\n\n### Runtime Commands\n\n```bash\nyamcp run \u003cyam-workspace-name\u003e   # Start the gateway with specified workspace\nyamcp log                    # View server communication logs\n```\n\n---\n\n## ✅ Command Reference\n\n| Command           | Description             | Example                              |\n| ----------------- | ----------------------- | ------------------------------------ |\n| `server add`      | Add a new MCP server    | `yamcp server add`                   |\n| `server list`     | List configured servers | `yamcp server list`                  |\n| `server remove`   | Remove a server         | `yamcp server remove [name]`         |\n| `server import`   | Import server config    | `yamcp server import [config]`       |\n| `yam create`      | Create workspace        | `yamcp yam create`                   |\n| `yam list`        | List workspaces         | `yamcp yam list`                     |\n| `yam list --name` | Show workspace details  | `yamcp yam list --name my-workspace` |\n| `yam edit`        | Edit workspace          | `yamcp yam edit`                     |\n| `yam scan  `      | Scan workspace          | `yamcp yam scan   [workspace-name]`  |\n| `yam delete`      | Delete workspace        | `yamcp yam delete [workspace-name]`  |\n| `run`             | Start gateway           | `yamcp run \u003cworkspace-name\u003e`         |\n| `log`             | View logs               | `yamcp log`                          |\n\n---\n\n## 🏗️ System Architecture\n\n```mermaid\ngraph TB\n    CLI[CLI Commands]\n    GW[McpGateway]\n    GS[GatewayServer]\n    GR[GatewayRouter]\n    LOG[Logger]\n    STORE[(Store)]\n    AI_APP[AI App]\n\n    %% CLI Command Flow\n    CLI --\u003e|manages| STORE\n    CLI --\u003e|runs| GW\n\n    %% Gateway Components\n    GW --\u003e|uses| GS\n    GW --\u003e|uses| GR\n    GW --\u003e|logs| LOG\n\n    %% Server \u0026 Router\n    GS --\u003e|stdio transport| AI_APP\n    GR --\u003e|connects to| SERVERX\n    GR --\u003e|connects to| SERVERY\n\n    %% Data Store\n    STORE --\u003e|loads config| GW\n\n    %% External MCP Servers\n    subgraph \"Workspace Servers\"\n        SERVERX[\"Server x (Stdio)\"]\n        SERVERY[\"Server y (SSE)\"]\n    end\n    %% Store Components\n    subgraph \"Configuration Store\"\n        PROVIDERS[(Provider Config)]\n        WORKSPACES[(Workspace Config)]\n    end\n    STORE --- PROVIDERS\n    STORE --- WORKSPACES\n\n    classDef primary fill:#2374ab,stroke:#2374ab,color:#fff\n    classDef secondary fill:#ff7e67,stroke:#ff7e67,color:#fff\n    classDef store fill:#95b8d1,stroke:#95b8d1,color:#fff\n\n    class GW,GS,GR primary\n    class CLI,AI_APP secondary\n    class STORE,PROVIDERS,WORKSPACES store\n```\n\nThe diagram shows the main components of the YAMCP system:\n\n- **CLI Commands**: User interface for managing servers and workspaces\n- **McpGateway**: Core component that coordinates the Gateway Server and Router\n- **GatewayServer**: Handles communication with AI Apps via stdio transport\n- **GatewayRouter**: Manages connections to configured MCP servers\n- **Logger**: Provides consolidated logging for all components\n- **Store**: Manages configuration for providers and workspaces\n- **MCP Servers**: Both local (stdio) and remote (SSE) servers that provide MCP services\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhamidra%2Fyamcp","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fhamidra%2Fyamcp","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhamidra%2Fyamcp/lists"}