{"id":34765947,"url":"https://github.com/stewones/mcpland","last_synced_at":"2026-01-20T17:27:38.372Z","repository":{"id":312211763,"uuid":"1045965656","full_name":"stewones/mcpland","owner":"stewones","description":"Building blocks for implementing Model Context Protocol (MCP) tools","archived":false,"fork":false,"pushed_at":"2025-09-08T20:00:13.000Z","size":7190,"stargazers_count":0,"open_issues_count":2,"forks_count":1,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-11-19T01:25:25.764Z","etag":null,"topics":["angular","mcp","model-context-protocol"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/stewones.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-08-28T01:42:35.000Z","updated_at":"2025-09-08T18:25:36.000Z","dependencies_parsed_at":"2025-08-29T09:23:30.928Z","dependency_job_id":"17b19f4b-9c89-4c74-88cc-ed4c2db5e9e7","html_url":"https://github.com/stewones/mcpland","commit_stats":null,"previous_names":["stewones/mcpland"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/stewones/mcpland","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/stewones%2Fmcpland","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/stewones%2Fmcpland/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/stewones%2Fmcpland/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/stewones%2Fmcpland/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/stewones","download_url":"https://codeload.github.com/stewones/mcpland/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/stewones%2Fmcpland/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28022964,"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","status":"online","status_checked_at":"2025-12-25T02:00:05.988Z","response_time":58,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"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":["angular","mcp","model-context-protocol"],"created_at":"2025-12-25T07:12:54.169Z","updated_at":"2025-12-25T07:12:58.649Z","avatar_url":"https://github.com/stewones.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# MCPLand\n\n[![Tests](./assets/test.svg)](https://github.com/stewones/mcpland/tree/main/test/src)\n[![Coverage](./assets/coverage.svg)](https://app.codecov.io/github/stewones/mcpland)\n[![NPM Version](https://img.shields.io/npm/v/mcpland)](https://www.npmjs.com/package/mcpland)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://github.com/stewones/mcpland/blob/main/LICENSE)\n\nMCPLand is a TypeScript framework for building and managing **Model Context Protocol (MCP) tools** with embedded context search capabilities. It provides a unified platform for creating AI-powered tools that can fetch, process, and search contextual information from various sources.\n\n## Content\n\n- [Installation](#installation)\n- [Usage](#usage)\n  - [Quick Start](#quick-start)\n  - [Commands](#commands)\n    - [`mcp init`](#mcp-init)\n    - [`mcp new`](#mcp-new)\n    - [`mcp serve`](#mcp-serve)\n    - [`mcp link`](#mcp-link)\n  - [Global Options](#global-options)\n- [Available MCPs](#available-mcps)\n- [Architecture](#architecture)\n  - [Data Flow](#data-flow)\n  - [Technical Features](#technical-features)\n    - [Embedding-Powered Search](#embedding-powered-search)\n    - [Plugin Architecture](#plugin-architecture)\n    - [Production Ready](#production-ready)\n  - [MCP Creation](#mcp-creation)\n  - [Integration Points](#integration-points)\n- [Roadmap](#roadmap)\n- [License](#license)\n\n\n# Installation\n\n```bash\nbun install -g mcpland\n```\n\n# Usage\n\n## Quick Start\n\n```bash\n# Initialize a new MCP project\nmcp init\n\n# Scaffold a new MCP (inside the project)\nmcp new my-mcp\n\n# Link with Cursor IDE (stdio mode)\nmcp link cursor\n\n# Or link with Cursor IDE (SSE mode)\nmcp link cursor --sse\n\n# Start SSE server (required for SSE mode)\nmcp serve\n```\n\n## Commands\n\n### `mcp init`\n\nInitialize a new MCP project with interactive setup.\n\n**Usage:**\n```bash\nmcp init\n```\n\n**What it does:**\n- Creates a new project directory (if needed)\n- Sets up `package.json` with mcpland dependency\n- Creates `mcpland.json` configuration file\n- Downloads and installs selected MCP tools\n- Sets up environment variables\n- Configures `.gitignore` and `.env` files\n- Installs dependencies automatically\n\n**Interactive prompts:**\n- Project name (if no package.json exists)\n- Source directory for MCPs (default: `src/mcps`)\n- OpenAI API key\n- Selection of available MCP tools from registry\n\n### `mcp new`\n\nScaffold a new MCP from the [base template](https://github.com/stewones/mcpland/tree/main/src/mcps/_).\n\n**Usage:**\n```bash\nmcp new [name]\n```\n\n**Arguments:**\n- `name` - Optional MCP name. If omitted, it will be asked for.\n\n**What it does:**\n- Creates `src/mcps/\u003cname\u003e/index.ts`\n- Creates an initial tool at `src/mcps/\u003cname\u003e/tools/\u003ctool\u003e/index.ts`\n- Prints next steps to edit your MCP and add more tools.\n\n**Interactive prompts:**\n- MCP name (if not provided as an argument)\n- MCP description\n- Initial tool name (e.g., `docs`)\n- Tool description\n\n**Examples:**\n```bash\nmcp new                    # Fully interactive\nmcp new my-mcp             # Skips name prompt, asks for the rest\n```\n\n**Notes:**\n- Run this command inside your project root (where `mcpland.json` lives). If `mcp init` created a new folder, `cd` into it first.\n\n### `mcp serve`\n\nStart the MCPLand SSE (Server-Sent Events) server.\n\n**Usage:**\n```bash\nmcp serve [options]\n```\n\n**Options:**\n- `--port, -p \u003cnumber\u003e` - Port to run the SSE server on (default: 1337)\n\n**Examples:**\n```bash\nmcp serve                    # Start server on default port 1337\nmcp serve --port 3000        # Start server on port 3000\nmcp serve -p 8080            # Start server on port 8080 (short form)\n```\n\n**Note:** This command is required when using SSE transport mode with Cursor.\n\n### `mcp link`\n\nConfigure Cursor IDE integration.\n\n**Usage:**\n```bash\nmcp link [options]\n```\n\n**Aliases:**\n- `mcp link:cursor`\n- `mcp cursor`\n\n**Options:**\n- `--sse` - Use SSE transport instead of stdio (default: false)\n\n**Examples:**\n```bash\nmcp link cursor             # Configure stdio mode (default)\nmcp link cursor --sse       # Configure SSE mode\nmcp cursor --sse            # Alternative syntax\n```\n\n**What it does:**\n- Creates `.cursor/mcp.json` configuration file\n- Sets up MCP server connection for Cursor IDE\n- Configures environment variables (stdio mode)\n- Sets up SSE endpoint URL (SSE mode)\n\n**Transport Modes:**\n- **stdio mode** (default): Direct process communication, automatically managed by Cursor\n- **SSE mode**: HTTP-based communication, requires running `mcp serve` separately\n\n## Global Options\n\n```bash\nmcp --version, -v           # Show version number\nmcp --help, -h              # Show all commands and global help\nmcp \u003ccommand\u003e --help        # Show help for specific command\n```\n\n**Examples:**\n```bash\nmcp --help                  # Show general help and command list\nmcp init --help             # Show help for init command\nmcp new --help              # Show help for new command\nmcp serve --help            # Show help for serve command\nmcp link --help             # Show help for link command\n```\n\n# Available MCPs\n\nMCPLand comes with built-in MCPs that you can use out of the box. These are automatically available during project initialization.\n\n## Angular MCP\n\n**Source:** [`src/mcps/angular/index.ts`](src/mcps/angular/index.ts)\n\nThe Angular MCP provides access to Angular's official documentation and context for AI-powered development assistance.\n\n**Tools:**\n- **`angular-docs`** - Search through Angular's comprehensive documentation\n  - **Context Source:** [Angular LLM Context](https://angular.dev/context/llm-files/llms-full.txt)\n  - **Capabilities:** Semantic search through Angular docs, guides, API references, and best practices\n  - **Usage:** Ask questions about Angular components, directives, services, routing, forms, and more\n\n**Example queries:**\n- \"What is modern Angular?\"\n- \"How do I create a reactive form in Angular?\"\n- \"What's the difference between ViewChild and ContentChild?\"\n- \"Show me how to implement lazy loading for routes\"\n- \"How to handle HTTP errors in Angular?\"\n\n# Architecture\n\n![architecture](./assets/architecture.svg)\n\n## Data Flow\n\n1. 📥 Context Ingestion\n   `External Source → Fetcher → Chunker → Embedder → SQLite Store`\n\n2. 🔍 Query Processing  \n   `LLM Query → MCP Server → Tool Handler → Vector Search → Ranked Results`\n\n3. 📤 Response Generation\n   `Search Results → Context Assembly → MCP Response → LLM Client`\n\n\n## Technical Features\n\n### Embedding-Powered Search\n- **Semantic search** capabilities beyond keyword matching\n- **Relevance scoring** with configurable limits\n- **Source isolation** for multi-context environments\n\n### Plugin Architecture\n- **Auto-discovery** of MCP implementations\n- **Tool registration** with validation\n- **Modular design** for easy extension\n\n### Production Ready\n- **Comprehensive testing** with Vitest\n- **Type safety** throughout with TypeScript\n- **Error handling** and logging\n\n\n## MCP Creation\n```typescript\n// Create new MCP in src/mcps/your-mcp/\nclass YourMCP extends MCPLand {\n  constructor() {\n    super({ name: 'your-mcp', description: 'Your description' });\n  }\n}\n\n// Create tools in src/mcps/your-mcp/tools/\nclass YourTool extends McpTool {\n  async fetchContext(): Promise\u003cstring\u003e {\n    // Fetch your context\n  }\n  \n  async handleContext(args: unknown): Promise\u003cServerResult\u003e {\n    // Handle search queries\n  }\n}\n```\n\n## Integration Points\n- **Cursor IDE integration** via link command\n- **Multiple LLM clients** via MCP protocol\n- **External APIs** and local files as context sources\n- **Custom embedding models** and search algorithms\n\n# Roadmap\n\n- [x] Add ability to serve SSE requests\n- [ ] Add ability to schedule context updates\n- [ ] Add ability to link with cursor globally\n- [x] Add ability to scaffold new mcps\n\n# License\n\nMIT\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fstewones%2Fmcpland","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fstewones%2Fmcpland","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fstewones%2Fmcpland/lists"}