diff --git a/docs/.vitepress/config/en.ts b/docs/.vitepress/config/en.ts index 7653df4b..f2f473a1 100644 --- a/docs/.vitepress/config/en.ts +++ b/docs/.vitepress/config/en.ts @@ -150,6 +150,9 @@ function sidebar(): DefaultTheme.Sidebar { text: 'mcp', link: '/commands/mcp/', items: [ + { text: 'install', link: '/commands/mcp/install' }, + { text: 'uninstall', link: '/commands/mcp/uninstall' }, + { text: 'search', link: '/commands/mcp/search' }, { text: 'add', link: '/commands/mcp/add' }, { text: 'remove', link: '/commands/mcp/remove' }, { text: 'update', link: '/commands/mcp/update' }, @@ -159,6 +162,11 @@ function sidebar(): DefaultTheme.Sidebar { { text: 'tokens', link: '/commands/mcp/tokens' }, ], }, + { + text: 'registry', + link: '/commands/registry/', + items: [{ text: 'search', link: '/commands/registry/search' }], + }, { text: 'preset', link: '/commands/preset/', @@ -208,6 +216,16 @@ function sidebar(): DefaultTheme.Sidebar { { text: 'Pagination', link: '/reference/pagination' }, ], }, + { + text: 'Internal Tools', + link: '/reference/internal-tools/', + items: [ + { text: 'Overview', link: '/reference/internal-tools/' }, + { text: 'Discovery Tools', link: '/reference/internal-tools/discovery' }, + { text: 'Installation Tools', link: '/reference/internal-tools/installation' }, + { text: 'Management Tools', link: '/reference/internal-tools/management' }, + ], + }, { text: 'Configuration', items: [ diff --git a/docs/.vitepress/config/zh.ts b/docs/.vitepress/config/zh.ts index 7cb0c248..e23600f5 100644 --- a/docs/.vitepress/config/zh.ts +++ b/docs/.vitepress/config/zh.ts @@ -160,6 +160,9 @@ function sidebar(): DefaultTheme.Sidebar { text: 'mcp', link: '/zh/commands/mcp/', items: [ + { text: 'install', link: '/zh/commands/mcp/install' }, + { text: 'uninstall', link: '/zh/commands/mcp/uninstall' }, + { text: 'search', link: '/zh/commands/mcp/search' }, { text: 'add', link: '/zh/commands/mcp/add' }, { text: 'remove', link: '/zh/commands/mcp/remove' }, { text: 'update', link: '/zh/commands/mcp/update' }, @@ -169,6 +172,11 @@ function sidebar(): DefaultTheme.Sidebar { { text: 'tokens', link: '/zh/commands/mcp/tokens' }, ], }, + { + text: 'registry', + link: '/zh/commands/registry/', + items: [{ text: 'search', link: '/zh/commands/registry/search' }], + }, { text: 'preset', link: '/zh/commands/preset/', @@ -215,6 +223,16 @@ function sidebar(): DefaultTheme.Sidebar { text: 'API 参考', items: [{ text: '健康检查 API', link: '/zh/reference/health-check' }], }, + { + text: '内部工具', + link: '/zh/reference/internal-tools/', + items: [ + { text: '概述', link: '/zh/reference/internal-tools/' }, + { text: '发现工具', link: '/zh/reference/internal-tools/discovery' }, + { text: '安装工具', link: '/zh/reference/internal-tools/installation' }, + { text: '管理工具', link: '/zh/reference/internal-tools/management' }, + ], + }, { text: '配置', items: [ diff --git a/docs/en/commands/mcp/index.md b/docs/en/commands/mcp/index.md index fd1af842..58d90a82 100644 --- a/docs/en/commands/mcp/index.md +++ b/docs/en/commands/mcp/index.md @@ -20,15 +20,44 @@ head: Manage MCP server configurations within your 1MCP instance. -These commands allow you to add, remove, update, and manage the lifecycle of the MCP servers that 1MCP will proxy. +These commands allow you to discover, install, configure, and manage the lifecycle of MCP servers through both manual configuration and the 1MCP registry. -For a detailed guide on server management, including transport types and best practices, please see the **[Server Management Guide](../../guide/essentials/server-management)**. +For a detailed guide on server management, including registry-based installation and best practices, please see the **[Server Management Guide](../../guide/essentials/server-management)**. -## Commands +## Registry-Based Commands (Recommended) + +### [install](./install) + +Install MCP servers from the 1MCP registry with automatic dependency resolution and version management. + +```bash +npx -y @1mcp/agent mcp install filesystem +npx -y @1mcp/agent mcp install --interactive +``` + +### [uninstall](./uninstall) + +Safely remove MCP servers with automatic backup creation and dependency validation. + +```bash +npx -y @1mcp/agent mcp uninstall filesystem +npx -y @1mcp/agent mcp uninstall test-server --force +``` + +### [search](./search) + +Search the MCP registry for available servers. + +```bash +npx -y @1mcp/agent mcp search database +npx -y @1mcp/agent mcp search --category=filesystem +``` + +## Manual Configuration Commands ### [add](./add) -Add a new MCP server to the configuration. +Manually add a new MCP server to the configuration. ```bash npx -y @1mcp/agent mcp add my-server --type=stdio --command="node server.js" @@ -85,4 +114,5 @@ npx -y @1mcp/agent mcp tokens --model=gpt-3.5-turbo --format=summary ## See Also - **[Server Management Guide](../../guide/essentials/server-management)** +- **[Registry Commands](../registry/)** - Server discovery and installation - **[App Consolidation Guide](../../guide/integrations/app-consolidation)** diff --git a/docs/en/commands/mcp/install.md b/docs/en/commands/mcp/install.md new file mode 100644 index 00000000..ac02bc69 --- /dev/null +++ b/docs/en/commands/mcp/install.md @@ -0,0 +1,227 @@ +--- +title: mcp install +description: Install MCP servers from the 1MCP registry +head: + - [ + 'meta', + { + name: 'keywords', + content: 'MCP install,registry server installation,interactive installation,server discovery', + }, + ] + - ['meta', { property: 'og:title', content: '1MCP Install Command - Registry Server Installation' }] + - [ + 'meta', + { + property: 'og:description', + content: 'Install MCP servers from the registry with interactive installation and version management.', + }, + ] +--- + +# mcp install + +Install MCP servers from the 1MCP registry with automatic dependency resolution and version management. The install command provides both interactive installation and direct server installation by name. + +> **Note**: This is the recommended way to add MCP servers to your configuration. For manual configuration, see the [add command](add.md). + +## Synopsis + +Launch interactive installation wizard: + +```bash +npx -y @1mcp/agent mcp install +``` + +Install a server by name from the registry: + +```bash +npx -y @1mcp/agent mcp install +``` + +Install with specific version: + +```bash +npx -y @1mcp/agent mcp install @ +``` + +Preview installation without making changes: + +```bash +npx -y @1mcp/agent mcp install --dry-run +``` + +Force reinstallation: + +```bash +npx -y @1mcp/agent mcp install --force +``` + +## Arguments + +- **``** (optional) + - Server name or name@version to install. Can include full registry ID (e.g., `io.github.user/filesystem`). + - **Required**: No + +## Global Options + +This command supports all global options: + +- **`--config, -c `** - Specify configuration file path +- **`--config-dir, -d `** - Path to the config directory + +## Command-Specific Options + +- **`--interactive, -i`** + - Launch interactive installation wizard. This is the default when no server name is provided. + +- **`--force`** + - Force installation even if the server already exists. Overwrites existing configuration. + +- **`--dry-run`** + - Show what would be installed without making any changes to your configuration. + +- **`--verbose, -v`** + - Display detailed installation information. + +## Examples + +### Basic Server Installation + +Install the latest version of the filesystem server: + +```bash +npx -y @1mcp/agent mcp install filesystem +``` + +Install a specific version: + +```bash +npx -y @1mcp/agent mcp install filesystem@1.2.0 +``` + +### Interactive Installation + +Launch the interactive installation wizard to browse and install servers: + +```bash +npx -y @1mcp/agent mcp install +``` + +Or explicitly request interactive mode: + +```bash +npx -y @1mcp/agent mcp install --interactive +``` + +The interactive mode will guide you through: + +1. **Server Discovery** - Browse available servers by category +2. **Version Selection** - Choose compatible versions +3. **Configuration** - Set server-specific options +4. **Installation** - Confirm and install with dependencies + +### Installation Preview + +Preview what would be installed without making changes: + +```bash +npx -y @1mcp/agent mcp install filesystem --dry-run + +# Output: +# 📦 Installation Preview: filesystem@latest +# Server: filesystem - File system access and management +# Use without --dry-run to perform actual installation +``` + +### Force Reinstallation + +Replace an existing server configuration: + +```bash +npx -y @1mcp/agent mcp install filesystem --force +``` + +### Verbose Installation + +See detailed installation process including dependency resolution: + +```bash +npx -y @1mcp/agent mcp install airtable --verbose + +# Output: +# 🔍 Resolving dependencies for airtable@2.1.0... +# ✓ Dependency check complete +# 📥 Downloading server metadata... +# ✓ Validating server configuration +# ⚙️ Generating configuration... +# ✓ Server installed successfully as 'airtable' +``` + +## Interactive Workflow + +When using `--interactive` or running without arguments, the install command launches a guided wizard that helps you: + +1. **Search** for servers by name or browse categories +2. **Select** a server and review its capabilities +3. **Choose** a version (stable vs latest) +4. **Configure** server-specific parameters +5. **Confirm** installation + +## Registry Features + +- **Server Discovery**: Search and browse available MCP servers +- **Version Management**: Install specific versions with compatibility checking +- **Dependency Resolution**: Automatically handle required dependencies +- **Security Validation**: Verify server integrity and authenticity + +## Configuration Output + +Installed servers are added to your `mcp.json` configuration with registry metadata: + +```json +{ + "mcpServers": { + "filesystem": { + "command": "npx", + "args": ["-y", "@modelcontextprotocol/server-filesystem", "/home/user"], + "tags": ["filesystem", "files", "local"], + "_registry": { + "name": "filesystem", + "version": "1.2.0", + "installedAt": "2024-01-15T10:30:00Z", + "source": "1mcp-registry" + } + } + } +} +``` + +## Error Handling + +The install command provides helpful error messages for common scenarios: + +```bash +# Server not found +npx -y @1mcp/agent mcp install nonexistent-server +# Error: Server 'nonexistent-server' not found in registry +# Suggestions: filesystem, git, database, search + +# Version not available +npx -y @1mcp/agent mcp install filesystem@99.99.99 +# Error: Version 99.99.99 not available for 'filesystem' +# Available versions: 1.2.0, 1.1.0, 1.0.0 + +# Already installed +npx -y @1mcp/agent mcp install filesystem +# Error: Server 'filesystem' already installed +# Use --force to reinstall or mcp update to upgrade +``` + +## See Also + +- **[Registry Search](../registry/search.md)** - Search the registry for available servers +- **[mcp uninstall](uninstall.md)** - Remove installed servers +- **[mcp update](update.md)** - Update installed servers +- **[Server Management Guide](../../guide/essentials/server-management.md)** - Complete server management overview +- **[Registry Commands](../registry/)** - Full registry command documentation diff --git a/docs/en/commands/mcp/search.md b/docs/en/commands/mcp/search.md new file mode 100644 index 00000000..b2114d9b --- /dev/null +++ b/docs/en/commands/mcp/search.md @@ -0,0 +1,62 @@ +--- +title: MCP Search Command - Registry Server Discovery +description: Search the MCP registry for available servers. This command is an alias for 'registry search' and provides quick access to server discovery. +head: + - ['meta', { name: 'keywords', content: 'MCP search,registry server discovery,server browsing,filtering' }] + - ['meta', { property: 'og:title', content: '1MCP Search Command - Registry Server Discovery' }] + - [ + 'meta', + { property: 'og:description', content: 'Search the MCP registry for available servers with filtering options.' }, + ] +--- + +# mcp search + +Search the MCP registry for available servers. This command is a **convenience alias** for the `registry search` command with limited options. For advanced filtering and options, use [registry search](../registry/search.md) directly. + +## Synopsis + +Search for servers by query: + +```bash +npx -y @1mcp/agent mcp search +``` + +Browse all available servers: + +```bash +npx -y @1mcp/agent mcp search +``` + +## Arguments + +`` (optional) +: Search query string to match against server names, descriptions, and tags. + +## Limitations + +Since this is an alias to `registry search`, it only supports basic search functionality. Advanced filtering options like `--status`, `--type`, `--transport`, and `--format` are only available in the full [registry search](../registry/search.md) command. + +## Examples + +### Basic Search + +Search for database-related servers: + +```bash +npx -y @1mcp/agent mcp search database +``` + +### Browse All Servers + +List all available servers: + +```bash +npx -y @1mcp/agent mcp search +``` + +## See Also + +- **[registry search](../registry/search.md)** - Full registry search command with advanced options +- **[registry commands](../registry/)** - Complete registry command documentation +- **[mcp install](install.md)** - Install servers found through search diff --git a/docs/en/commands/mcp/uninstall.md b/docs/en/commands/mcp/uninstall.md new file mode 100644 index 00000000..0d19293a --- /dev/null +++ b/docs/en/commands/mcp/uninstall.md @@ -0,0 +1,195 @@ +--- +title: MCP Uninstall Command - Safe Server Removal +description: Safely uninstall MCP servers with automatic backup creation and dependency checking. Remove servers and clean up configurations. +head: + - ['meta', { name: 'keywords', content: 'MCP uninstall,server removal,backup creation,safe deletion' }] + - ['meta', { property: 'og:title', content: '1MCP Uninstall Command - Safe Server Removal' }] + - [ + 'meta', + { + property: 'og:description', + content: 'Safely uninstall MCP servers with backup creation and dependency checking.', + }, + ] +--- + +# mcp uninstall + +Safely remove MCP servers from your configuration with automatic backup creation and dependency validation. The uninstall command ensures safe removal with rollback capabilities. + +## Synopsis + +Remove a server with confirmation and backup: + +```bash +npx -y @1mcp/agent mcp uninstall +``` + +Skip confirmation prompts: + +```bash +npx -y @1mcp/agent mcp uninstall --force +``` + +Remove without creating backup: + +```bash +npx -y @1mcp/agent mcp uninstall --no-backup +``` + +Remove only configuration (keep server data): + +```bash +npx -y @1mcp/agent mcp uninstall --no-remove-config +``` + +## Arguments + +`` (required) +: The name of the server to uninstall. Must be an existing server in your configuration. + +## Global Options + +- **`--config, -c `** - Specify configuration file path +- **`--config-dir, -d `** - Path to the config directory + +## Command-Specific Options + +- **`--force, -y`** + - Skip confirmation prompts and proceed with uninstallation + - **Default**: `false` + +- **`--backup`** + - Create backup before removal + - **Default**: `true` + +- **`--remove-config`** + - Remove server configuration from mcp.json + - **Default**: `true` + +- **`--verbose, -v`** + - Display detailed uninstallation information + - **Default**: `false` + +## Examples + +### Basic Server Removal + +Remove a server with confirmation and backup: + +```bash +npx -y @1mcp/agent mcp uninstall filesystem + +# Output: +# 🔄 Preparing to uninstall 'filesystem'... +# ℹ️ Server 'filesystem' is currently running +# ℹ️ Server has the following capabilities: file_read, file_write, list_directory +# ℹ️ No other servers depend on 'filesystem' +# +# ⚠️ This will: +# • Stop the 'filesystem' server +# • Remove server configuration from mcp.json +# • Create backup at: ~/.config/1mcp/backups/mcp-20240115-103000.json +# +# Continue? (y/N): y +# +# ✓ Server 'filesystem' stopped successfully +# ✓ Configuration removed from mcp.json +# ✓ Backup created: ~/.config/1mcp/backups/mcp-20240115-103000.json +# ✅ Uninstall completed successfully +``` + +### Force Uninstall + +Skip confirmation prompts: + +```bash +npx -y @1mcp/agent mcp uninstall filesystem --force + +# Output: +# 🔄 Uninstalling 'filesystem'... +# ✓ Server stopped +# ✓ Configuration removed +# ✓ Backup created +# ✅ Uninstall completed +``` + +### Uninstall Without Backup + +Remove server without creating backup (not recommended): + +```bash +npx -y @1mcp/agent mcp uninstall test-server --no-backup + +# Output: +# ⚠️ Skipping backup creation +# 🔄 Uninstalling 'test-server'... +# ✓ Server removed +# ✅ Uninstall completed without backup +``` + +### Verbose Uninstall + +See detailed uninstallation process: + +```bash +npx -y @1mcp/agent mcp uninstall database --verbose + +# Output: +# 🔍 Analyzing server 'database'... +# • Configuration found in mcp.json +# • Server is currently running (PID: 12345) +# • Dependencies: 0 servers depend on this +# • Backup location: ~/.config/1mcp/backups/mcp-20240115-103500.json +# +# 🛡️ Safety checks passed +# 🔄 Proceeding with uninstallation... +# • Gracefully stopping server process +# • Removing from active server list +# • Updating mcp.json configuration +# • Creating configuration backup +# +# ✅ Uninstall completed successfully +``` + +## Safety Features + +The uninstall command includes built-in safety measures: + +- **Dependency Checking**: Warns if other servers depend on the one being removed +- **Automatic Backups**: Creates timestamped backups before removal (`~/.config/1mcp/backups/`) +- **Graceful Shutdown**: Properly stops servers before removal with SIGTERM/SIGKILL handling + +## Error Handling + +Common error scenarios: + +```bash +# Server not found +npx -y @1mcp/agent mcp uninstall nonexistent-server +# Error: Server 'nonexistent-server' not found in configuration + +# Permission issues +npx -y @1mcp/agent mcp uninstall system-server +# Error: Permission denied when stopping server process +``` + +## Backup Restoration + +Restore from backup if needed: + +```bash +# List available backups +ls ~/.config/1mcp/backups/ + +# Restore from backup +cp ~/.config/1mcp/backups/mcp-20240115-103000.json ~/.config/1mcp/mcp.json +``` + +## See Also + +- **[mcp install](install.md)** - Install servers from registry +- **[mcp disable](enable-disable.md)** - Temporarily disable servers +- **[mcp list](list.md)** - List installed servers +- **[Server Management Guide](../../guide/essentials/server-management.md)** - Complete server management overview +- **[Configuration Reference](../../reference/mcp-servers.md)** - Configuration file structure diff --git a/docs/en/commands/registry/index.md b/docs/en/commands/registry/index.md new file mode 100644 index 00000000..12fa97a0 --- /dev/null +++ b/docs/en/commands/registry/index.md @@ -0,0 +1,294 @@ +--- +title: Registry Commands - MCP Server Discovery and Management +description: Complete guide to 1MCP registry commands for server discovery, installation, version management, and dependency resolution. +head: + - ['meta', { name: 'keywords', content: 'MCP registry,server discovery,version management,dependency resolution' }] + - ['meta', { property: 'og:title', content: '1MCP Registry Commands - Server Discovery and Management' }] + - [ + 'meta', + { + property: 'og:description', + content: 'Discover, install, and manage MCP servers through the 1MCP registry with version control and dependency management.', + }, + ] +--- + +# Registry Commands + +The 1MCP registry provides centralized server discovery, version management, and dependency resolution for MCP servers. Registry commands enable you to search for servers, view detailed information, check versions, and manage server installations. + +> **Quick Start**: Use `npx @1mcp/agent mcp install ` for streamlined installation. + +## Overview + +The 1MCP registry is a centralized repository that: + +- **Discovers** available MCP servers across categories +- **Manages** versioning and compatibility information +- **Resolves** dependencies automatically +- **Validates** server integrity and security +- **Provides** detailed server metadata and documentation + +## Available Commands + +### Server Discovery + +- **[registry search](search.md)** - Search for servers by name, category, or tags + +## Registry Workflow + +### 1. Discovery + +Find servers that match your needs: + +```bash +# Search by category +npx -y @1mcp/agent registry search --category=filesystem + +# Search by functionality +npx -y @1mcp/agent registry search "database" + +# Browse all servers +npx -y @1mcp/agent registry search +``` + +### 2. Information Gathering + +Get detailed information about servers: + +```bash +# View server details +npx -y @1mcp/agent registry show filesystem + +# Check available versions +npx -y @1mcp/agent registry versions filesystem + +# See dependencies and requirements +npx -y @1mcp/agent registry show postgresql --deps +``` + +### 3. Installation + +Install servers with automatic dependency resolution: + +```bash +# Install latest version +npx -y @1mcp/agent mcp install filesystem + +# Install specific version +npx -y @1mcp/agent mcp install filesystem@1.2.0 + +# Install with interactive wizard +npx -y @1mcp/agent mcp install --interactive +``` + +### 4. Management + +Keep servers updated and managed: + +```bash +# Check for updates +npx -y @1mcp/agent registry updates + +# Update specific server +npx -y @1mcp/agent mcp update filesystem + +# Remove server +npx -y @1mcp/agent mcp uninstall filesystem +``` + +## Server Categories + +The registry organizes servers into functional categories: + +### System & File Management + +- **Filesystem** - File system access and operations +- **Database** - Database connectivity and operations +- **Storage** - Cloud storage and object management +- **Backup** - Data backup and recovery tools + +### Development Tools + +- **Git** - Version control and repository operations +- **Build** - Build systems and compilation tools +- **Testing** - Testing frameworks and utilities +- **Debugging** - Debugging and profiling tools + +### Web & Network + +- **HTTP** - HTTP client and API tools +- **Search** - Web search and information retrieval +- **Scraping** - Web scraping and data extraction +- **API** - API integration and management + +### Data Processing + +- **Analytics** - Data analysis and reporting +- **Machine Learning** - ML model serving and training +- **ETL** - Data transformation and pipelines +- **Visualization** - Data visualization tools + +### Communication + +- **Email** - Email sending and management +- **Chat** - Messaging and communication platforms +- **Calendar** - Calendar and scheduling tools +- **Notification** - Alert and notification systems + +## Server Metadata + +Each server in the registry includes comprehensive metadata: + +```json +{ + "name": "filesystem", + "displayName": "File System Server", + "description": "File system access and management capabilities", + "version": "1.2.0", + "category": "System", + "tags": ["filesystem", "files", "local", "storage"], + "maintainer": "Model Context Protocol Team", + "license": "MIT", + "homepage": "https://github.com/modelcontextprotocol/servers", + "repository": "https://github.com/modelcontextprotocol/servers/tree/main/src/filesystem", + "documentation": "https://docs.modelcontextprotocol.io/servers/filesystem", + "dependencies": [], + "engines": { + "node": ">=14.0.0" + }, + "platforms": ["linux", "darwin", "win32"], + "transport": ["stdio"], + "capabilities": { + "tools": ["read_file", "write_file", "list_directory", "create_directory"], + "resources": ["file://*"] + }, + "security": { + "trusted": true, + "sandboxed": false, + "permissions": ["filesystem"] + }, + "installation": { + "npm": "@modelcontextprotocol/server-filesystem", + "command": "npx", + "args": ["-y", "@modelcontextprotocol/server-filesystem"] + }, + "changelog": "https://github.com/modelcontextprotocol/servers/blob/main/CHANGELOG.md" +} +``` + +## Version Management + +The registry follows semantic versioning (SemVer): + +- **Major versions** - Breaking changes +- **Minor versions** - New features (backward compatible) +- **Patch versions** - Bug fixes (backward compatible) + +### Version Selection + +```bash +# Install latest stable +npx -y @1mcp/agent mcp install filesystem + +# Install specific major version +npx -y @1mcp/agent mcp install filesystem@1 + +# Install specific minor version +npx -y @1mcp/agent mcp install filesystem@1.2 + +# Install exact version +npx -y @1mcp/agent mcp install filesystem@1.2.0 + +# Install pre-release version +npx -y @1mcp/agent mcp install filesystem@2.0.0-beta.1 +``` + +## Security and Trust + +The registry includes security validation: + +- **Trusted Sources** - Verified maintainers and repositories +- **Vulnerability Scanning** - Automated security checks +- **Dependency Auditing** - Package dependency security analysis +- **Code Review** - Community review process + +## Private Registries + +For enterprise and private server management: + +```bash +# Configure private registry +npx -y @1mcp/agent registry config --add private.registry.com + +# Authenticate with private registry +npx -y @1mcp/agent registry login private.registry.com + +# Search private registry +npx -y @1mcp/agent registry search --registry=private.registry.com +``` + +## Integration with MCP Commands + +Registry commands integrate seamlessly with MCP commands: + +```bash +# These are equivalent: +npx -y @1mcp/agent registry search filesystem +npx -y @1mcp/agent mcp install --search filesystem + +# Install from registry search results +npx -y @1mcp/agent registry search database | head -5 | xargs -I {} npx -y @1mcp/agent mcp install {} + +# Check updates for all installed servers +npx -y @1mcp/agent registry updates --installed +``` + +## Cache Management + +Registry operations use local caching for performance: + +```bash +# Clear registry cache +npx -y @1mcp/agent registry cache --clear + +# Force refresh server information +npx -y @1mcp/agent registry show filesystem --refresh + +# Set cache expiration +npx -y @1mcp/agent registry config --cache-expire=1h +``` + +## Best Practices + +### Server Selection + +1. **Check Compatibility** - Ensure server matches your environment +2. **Review Dependencies** - Understand required dependencies +3. **Read Documentation** - Review server capabilities and limitations +4. **Check Maintenance** - Prefer actively maintained servers +5. **Test in Development** - Validate servers in non-production environments + +### Version Management + +1. **Use Specific Versions** - Pin versions for production stability +2. **Test Updates** - Validate new versions before upgrading +3. **Monitor Changelogs** - Track changes and deprecations +4. **Backup Configuration** - Keep backups of working configurations +5. **Rollback Plan** - Prepare downgrade strategies + +### Security + +1. **Verify Sources** - Only use servers from trusted maintainers +2. **Review Permissions** - Understand server access requirements +3. **Regular Updates** - Keep servers updated for security patches +4. **Isolate Environments** - Use separate configs for different environments +5. **Audit Dependencies** - Monitor dependency security updates + +## See Also + +- **[mcp install](../mcp/install.md)** - Install servers from registry +- **[mcp uninstall](../mcp/uninstall.md)** - Remove installed servers +- **[Server Management Guide](../../guide/essentials/server-management.md)** - Complete server management +- **[Configuration Reference](../../reference/mcp-servers.md)** - Configuration details +- **[Getting Started](../../guide/getting-started.md)** - Initial setup instructions diff --git a/docs/en/commands/registry/search.md b/docs/en/commands/registry/search.md new file mode 100644 index 00000000..dd4ed264 --- /dev/null +++ b/docs/en/commands/registry/search.md @@ -0,0 +1,294 @@ +--- +title: Registry Search Command - Server Discovery +description: Search the 1MCP registry for MCP servers by name, category, tags, or functionality. Filter results and find servers that match your specific requirements. +head: + - ['meta', { name: 'keywords', content: 'MCP registry search,server discovery,filtering,server lookup' }] + - ['meta', { property: 'og:title', content: '1MCP Registry Search Command - Server Discovery' }] + - [ + 'meta', + { + property: 'og:description', + content: 'Search the 1MCP registry for MCP servers with advanced filtering and discovery capabilities.', + }, + ] +--- + +# registry search + +Search the 1MCP registry for MCP servers using various filters and criteria. Find servers by name, category, tags, or functionality with advanced filtering options. + +## Synopsis + +Search for servers by name or keyword: + +```bash +npx -y @1mcp/agent registry search +``` + +Browse all available servers: + +```bash +npx -y @1mcp/agent registry search +``` + +Filter by transport type: + +```bash +npx -y @1mcp/agent registry search --transport=stdio +``` + +Advanced filtering with multiple criteria: + +```bash +npx -y @1mcp/agent registry search database --type=npm --format=json +``` + +## Arguments + +`` (optional) +: Search query string to match against server names, descriptions, and tags. Supports partial matching and fuzzy search. + +## Global Options + +- **`--config, -c `** - Specify configuration file path +- **`--config-dir, -d `** - Path to the config directory + +## Command-Specific Options + +- **`--status `** + - Filter by server status + - **Choices**: `active`, `archived`, `deprecated`, `all` + - **Default**: `active` + +- **`--type `** + - Filter by package registry type + - **Choices**: `npm`, `pypi`, `docker` + +- **`--transport `** + - Filter by transport method + - **Choices**: `stdio`, `sse`, `http` + +- **`--limit `** + - Maximum number of results to return + - **Default**: `20` + - **Maximum**: `100` + +- **`--cursor `** + - Pagination cursor for retrieving next page of results + +- **`--format `** + - Output format for search results + - **Choices**: `table`, `list`, `json` + - **Default**: `table` + +## Examples + +### Basic Search + +Search for filesystem-related servers: + +```bash +npx -y @1mcp/agent registry search filesystem +``` + +### Filter by Transport + +Find servers that use stdio transport: + +```bash +npx -y @1mcp/agent registry search --transport=stdio +``` + +### Filter by Package Type + +Search for npm packages only: + +```bash +npx -y @1mcp/agent registry search --type=npm database +``` + +### Limit Results + +Get only the first 5 results: + +```bash +npx -y @1mcp/agent registry search database --limit=5 +``` + +### JSON Output + +Get machine-readable results: + +```bash +npx -y @1mcp/agent registry search database --format=json +``` + +### List All Active Servers + +Browse all available servers: + +```bash +npx -y @1mcp/agent registry search --status=active +``` + +## Search Syntax + +### Query Format + +Search queries support flexible matching: + +```bash +# Exact name match +registry search filesystem + +# Partial name match +registry search file + +# Description match +registry search "file system" + +# Tag match +registry search storage + +# Fuzzy matching +registry search flsystm # Matches "filesystem" +``` + +### Special Operators + +Use special operators for advanced searches: + +```bash +# Exact phrase match +registry search "file system access" + +# Exclude terms +registry search database --not=mysql + +# Wildcard matching +registry search py* # Matches python, pytorch, etc. + +# Regular expressions +registry search --regex="^(git|svn|hg)$" +``` + +## Categories and Tags + +### Available Categories + +- **System** - File system, backup, utilities +- **Database** - Database servers and clients +- **Development** - Build tools, version control +- **Web** - HTTP clients, web scraping +- **Network** - Network protocols, APIs +- **Storage** - Cloud storage, object storage +- **Communication** - Email, chat, notifications +- **Data Processing** - Analytics, ML, ETL +- **Security** - Authentication, encryption +- **Monitoring** - Logging, metrics, alerts + +### Common Tags + +- **Transport**: stdio, http, sse +- **Platform**: linux, darwin, win32, web +- **Functionality**: api, cli, gui, batch +- **Language**: python, javascript, go, rust +- **Environment**: development, production, testing +- **Security**: trusted, verified, sandboxed + +## Sorting and Pagination + +### Sort Options + +```bash +# Sort by popularity (most downloaded) +registry search --sort=popularity + +# Sort by recently updated +registry search --sort=updated + +# Sort by name (alphabetical) +registry search --sort=name + +# Sort by creation date +registry search --sort=created + +# Sort by download count +registry search --sort=downloads +``` + +### Pagination + +Control result display: + +```bash +# Limit results +registry search --limit=10 + +# Skip first N results +registry search --offset=20 + +# Show all results (up to max 100) +registry search --limit=100 +``` + +## Registry Caching + +Search results are cached for performance: + +```bash +# Force refresh cache +registry search --refresh + +# Check cache status +registry status --cache + +# Clear cache +registry cache --clear +``` + +## Integration Examples + +### Pipeline to Install + +Search and install servers: + +```bash +# Search and install top result +registry search database --limit=1 --output=json | \ + jq -r '.results[0].name' | \ + xargs npx -y @1mcp/agent mcp install + +# Install all database servers +registry search --category=database --output=list | \ + xargs -n1 npx -y @1mcp/agent mcp install +``` + +### Update Check Automation + +Check for updates in scripts: + +```bash +#!/bin/bash +# Check for servers with updates +updates=$(registry search --updates --output=json) +count=$(echo "$updates" | jq '.total') + +if [ "$count" -gt 0 ]; then + echo "Found $count available updates:" + echo "$updates" | jq -r '.results[] | " • \(.name): \(.current) → \(.latest)"' + + # Ask user if they want to update + read -p "Update all servers? (y/N): " -n 1 -r + echo + if [[ $REPLY =~ ^[Yy]$ ]]; then + registry search --updates --output=list | \ + xargs -n1 npx -y @1mcp/agent mcp update + fi +fi +``` + +## See Also + +- **[mcp install](../mcp/install.md)** - Install servers from search results +- **[Server Management Guide](../../guide/essentials/server-management.md)** - Server management overview diff --git a/docs/en/guide/essentials/configuration.md b/docs/en/guide/essentials/configuration.md index cb77d1a0..b1d0ad37 100644 --- a/docs/en/guide/essentials/configuration.md +++ b/docs/en/guide/essentials/configuration.md @@ -61,6 +61,8 @@ All available command-line options and their corresponding environment variables | `--session-persist-interval` | `ONE_MCP_SESSION_PERSIST_INTERVAL` | Session persistence interval in minutes (number) | 5 | | `--session-background-flush` | `ONE_MCP_SESSION_BACKGROUND_FLUSH` | Session background flush interval in seconds (number) | 60 | | `--enable-client-notifications` | `ONE_MCP_ENABLE_CLIENT_NOTIFICATIONS` | Enable real-time client notifications (boolean) | true | +| `--enable-internal-tools` | `ONE_MCP_ENABLE_INTERNAL_TOOLS` | Enable ALL MCP internal tools for AI assistants (boolean) | false | +| `--internal-tools` | `ONE_MCP_INTERNAL_TOOLS` | Enable specific internal tool categories (discovery,installation,management,safe) | | | `--health-info-level` | `ONE_MCP_HEALTH_INFO_LEVEL` | Health endpoint information detail level ("full", "basic", "minimal") | "minimal" | | `--log-level` | `ONE_MCP_LOG_LEVEL` | Set the log level ("debug", "info", "warn", "error") | "info" | | `--log-file` | `ONE_MCP_LOG_FILE` | Write logs to a file in addition to console (disables console logging only for stdio transport) | | @@ -266,6 +268,50 @@ npx -y @1mcp/agent --tag-filter "web and api and not test" ONE_MCP_TAG_FILTER="network+api" npx -y @1mcp/agent ``` +### Internal Tools Options + +Control MCP internal tools exposure for AI assistants. + +**`--enable-internal-tools`** + +- **Purpose**: Enable ALL MCP internal tools for AI assistants +- **Default**: `false` +- **Environment**: `ONE_MCP_ENABLE_INTERNAL_TOOLS` + +**`--internal-tools `** + +- **Purpose**: Enable specific internal tool categories +- **Values**: Comma-separated categories: `discovery,installation,management,safe` +- **Default**: No categories enabled +- **Environment**: `ONE_MCP_INTERNAL_TOOLS` + +**Categories**: + +- `discovery` - Tools for discovering MCP servers (mcp*search, mcp_registry*\*) +- `installation` - Tools for installing/updating/removing servers (mcp_install, mcp_update, mcp_uninstall) +- `management` - Tools for managing server lifecycle (mcp_enable, mcp_disable, mcp_list, mcp_status, mcp_reload, mcp_edit) +- `safe` - Read-only tools only (subset of discovery and management) + +**Examples**: + +```bash +# Enable ALL internal tools +npx -y @1mcp/agent --enable-internal-tools + +# Enable only discovery and management tools +npx -y @1mcp/agent --internal-tools "discovery,management" + +# Enable only safe (read-only) tools +npx -y @1mcp/agent --internal-tools "safe" + +# Environment variables +ONE_MCP_ENABLE_INTERNAL_TOOLS=true npx -y @1mcp/agent + +ONE_MCP_INTERNAL_TOOLS="discovery,management" npx -y @1mcp/agent +``` + +**Important**: Internal tools are different from CLI commands. CLI commands are for human users, while internal tools are MCP protocol tools that AI assistants can use to automate server management tasks. For detailed information about available internal tools, see the **[Internal Tools Reference](../../reference/internal-tools.md)**. + ### Performance Options Control performance and resource usage behavior. diff --git a/docs/en/guide/essentials/server-management.md b/docs/en/guide/essentials/server-management.md index 116aa305..7600aced 100644 --- a/docs/en/guide/essentials/server-management.md +++ b/docs/en/guide/essentials/server-management.md @@ -1,21 +1,112 @@ --- -title: Server Management Guide - Transport Types and Best Practices -description: Learn how to manage MCP servers in 1MCP. Covers STDIO and HTTP transports, configuration best practices, and lifecycle management. +title: Server Management Guide - Registry-Based Installation and Configuration +description: Learn how to manage MCP servers in 1MCP using the registry-based approach for server discovery, installation, and lifecycle management. head: - - ['meta', { name: 'keywords', content: 'MCP server management,transport types,STDIO transport,HTTP transport' }] - - ['meta', { property: 'og:title', content: '1MCP Server Management Guide' }] + - [ + 'meta', + { + name: 'keywords', + content: 'MCP server management,registry installation,server discovery,lifecycle management', + }, + ] + - ['meta', { property: 'og:title', content: '1MCP Server Management Guide - Registry-Based Approach' }] - [ 'meta', { property: 'og:description', - content: 'Complete guide to managing MCP servers in 1MCP. Transport types and best practices.', + content: 'Complete guide to managing MCP servers in 1MCP using registry-based installation and configuration.', }, ] --- # Server Management Guide -This guide provides a detailed overview of managing MCP servers within your 1MCP instance. It covers transport types, configuration best practices, and advanced management workflows. +This guide provides a comprehensive overview of managing MCP servers within your 1MCP instance using the recommended registry-based approach for server discovery, installation, and lifecycle management. + +## Registry-Based Workflow (Recommended) + +The 1MCP registry provides a centralized repository for discovering, installing, and managing MCP servers with automatic dependency resolution and version management. This is the recommended approach for server management. + +### Quick Start + +Install your first server from the registry: + +```bash +# Search for available servers +npx -y @1mcp/agent registry search --category=filesystem + +# Install the filesystem server +npx -y @1mcp/agent mcp install filesystem + +# Or use the interactive wizard +npx -y @1mcp/agent mcp wizard +``` + +### Registry Workflow + +1. **Discovery** - Find servers that match your needs +2. **Selection** - Choose servers with version compatibility +3. **Installation** - Automatic dependency resolution and setup +4. **Configuration** - Server-specific customization +5. **Management** - Updates, removal, and lifecycle control + +### Registry Benefits + +- **Server Discovery** - Browse and search across hundreds of MCP servers +- **Version Management** - Install specific versions with compatibility checking +- **Dependency Resolution** - Automatic installation of required dependencies +- **Security Validation** - Verified servers with integrity checks +- **Update Management** - Easy updates with change tracking +- **Interactive Installation** - Guided setup with the configuration wizard + +### Installation Methods + +#### Direct Installation + +Install servers by name from the registry: + +```bash +# Install latest version +npx -y @1mcp/agent mcp install filesystem + +# Install specific version +npx -y @1mcp/agent mcp install filesystem@1.2.0 + +# Install with configuration +npx -y @1mcp/agent mcp install git --repository /path/to/project +``` + +#### Interactive Wizard + +Launch the configuration wizard for guided installation: + +```bash +# Start interactive wizard +npx -y @1mcp/agent mcp wizard + +# Start with predefined template +npx -y @1mcp/agent mcp wizard --template development +``` + +The wizard provides: + +- Server browsing by category +- Step-by-step configuration +- Compatibility checking +- Best practice recommendations + +#### Search and Install + +Search the registry and install from results: + +```bash +# Search for database servers +npx -y @1mcp/agent registry search database + +# Install search results +npx -y @1mcp/agent registry search database --limit=3 --output=list | \ + xargs -n1 npx -y @1mcp/agent mcp install +``` ## Transport Types @@ -76,33 +167,77 @@ Each server you define in 1MCP has a set of common configuration options: ## Server Management Workflow -A typical workflow for managing servers looks like this: +### Registry-Based Workflow (Recommended) + +The modern workflow using the registry provides automatic dependency resolution and version management: + +1. **Discover Servers**: Search the registry for servers that meet your needs. + + ```bash + # Search for development servers + npx -y @1mcp/agent registry search --category=development + + # Browse all available servers + npx -y @1mcp/agent mcp wizard + ``` + +2. **Install Servers**: Install servers with automatic configuration. + + ```bash + # Install the filesystem server + npx -y @1mcp/agent mcp install filesystem + + # Install specific version + npx -y @1mcp/agent mcp install git@1.2.0 + ``` + +3. **Verify Installation**: Check that servers are properly installed and running. -1. **Add a Server**: Add a new server to your 1MCP instance. ```bash - # Add a local git server - npx -y @1mcp/agent mcp add git-main --type=stdio --command="mcp-server-git" --args="--repository ." + npx -y @1mcp/agent mcp list + npx -y @1mcp/agent mcp status filesystem ``` -2. **Verify the Configuration**: List your servers and check the status of the new one. + +4. **Manage Updates**: Keep servers updated with latest versions. + ```bash - ONE_MCP_LOG_LEVEL=debug npx -y @1mcp/agent mcp list - npx -y @1mcp/agent mcp status git-main + # Check for available updates + npx -y @1mcp/agent registry search --updates + + # Update specific server + npx -y @1mcp/agent mcp update filesystem ``` -3. **Update as Needed**: Modify the server's configuration. For example, add a tag. + +5. **Manage Lifecycle**: Enable, disable, or remove servers as needed. + ```bash - npx -y @1mcp/agent mcp update git-main --tags=source-control,project-a + # Temporarily disable + npx -y @1mcp/agent mcp disable filesystem + + # Re-enable + npx -y @1mcp/agent mcp enable filesystem + + # Remove with backup + npx -y @1mcp/agent mcp uninstall filesystem ``` -4. **Manage its Lifecycle**: If you need to temporarily disable the server, you can do so without losing its configuration. + +### Manual Configuration Workflow (Advanced) + +For custom servers not available in the registry: + +1. **Add Server Manually**: Configure server details manually. + ```bash - npx -y @1mcp/agent mcp disable git-main - # ...later... - npx -y @1mcp/agent mcp enable git-main + npx -y @1mcp/agent mcp add custom-server --type=stdio --command="node server.js" ``` -5. **Remove When Done**: If you no longer need the server, you can permanently remove it. + +2. **Configure Settings**: Set server-specific options. ```bash - npx -y @1mcp/agent mcp remove git-main + npx -y @1mcp/agent mcp update custom-server --tags=custom,experimental --args="--port=3000" ``` +The registry-based approach is recommended for most users, with manual configuration reserved for custom or proprietary servers. + ## Best Practices ### Configuration diff --git a/docs/en/guide/features.md b/docs/en/guide/features.md index 6d4b0885..40c46728 100644 --- a/docs/en/guide/features.md +++ b/docs/en/guide/features.md @@ -31,6 +31,7 @@ head: - **🖥️ I use Claude Desktop** → [Claude Desktop Integration](/guide/integrations/claude-desktop) - **⚙️ I need server management** → [Server Management](/guide/essentials/server-management) - **🏷️ I want server filtering** → [Server Filtering](/guide/advanced/server-filtering) +- **🤖 I need AI automation** → [Internal Tools for AI Assistants](/reference/internal-tools) - **⚡ I need fast startup** → [Fast Startup](/guide/advanced/fast-startup) --- @@ -147,6 +148,19 @@ Perfect for: Multi-tenant environments, role-based access, environment separatio --- +## 🤖 [Internal Tools for AI Assistants](/reference/internal-tools) + +Empower AI assistants with programmatic MCP server management capabilities: + +- **🔍 Discovery Tools (5)** - Search registry, check availability, get server information +- **⚙️ Installation Tools (3)** - Install, update, uninstall servers with dependency resolution +- **🔧 Management Tools (6)** - Enable/disable servers, monitor health, edit configurations +- **🛡️ Safety Features** - Built-in validation, backups, rollback, and error recovery + +Perfect for: AI assistant automation, programmatic server management, DevOps workflows, intelligent monitoring + +--- + ## ⚡ [Fast Startup](/guide/advanced/fast-startup) Get 1MCP running instantly with asynchronous server loading: @@ -179,6 +193,7 @@ Perfect for: Development workflows, unreliable networks, large server configurat | **Claude Desktop** | ✅ Essential | 🔌 Integration | 🔧 Setup | 📊 Remote | 🛡️ Secure | | **Server Management** | 🚫 Hidden | ✅ Essential | ✅ Critical | ✅ Critical | ✅ Advanced | | **Server Filtering** | 🚫 Transparent | 🔧 Configurable | 🛡️ Access Ctrl | 🛡️ Policies | 🛡️ Multi-Tenant | +| **Internal Tools** | 🚫 Hidden | 🤖 Automation | 🔧 Management | ⚡ Critical | 🔧 Enterprise | **Legend**: ✅ Primary benefit | ⚡ Performance | 🔒 Security | 🔧 Technical | 🛡️ Protection | 📊 Monitoring | 🚫 Not relevant @@ -201,6 +216,7 @@ Perfect for: Development workflows, unreliable networks, large server configurat - **Claude Desktop** → [Claude Desktop Integration](/guide/integrations/claude-desktop) - **Server Management** → [Server Management Guide](/guide/essentials/server-management) - **Server Filtering** → [Server Filtering Guide](/guide/advanced/server-filtering) +- **AI Automation** → [Internal Tools Reference](/reference/internal-tools) - **Performance** → [Fast Startup Guide](/guide/advanced/fast-startup) - **Architecture** → [System Architecture](/reference/architecture) diff --git a/docs/en/reference/internal-tools.md b/docs/en/reference/internal-tools.md new file mode 100644 index 00000000..07697528 --- /dev/null +++ b/docs/en/reference/internal-tools.md @@ -0,0 +1,271 @@ +--- +title: MCP Internal Tools Reference +description: Complete reference documentation for 1MCP internal tools - MCP protocol tools for server discovery, installation, and management +head: + - [ + 'meta', + { name: 'keywords', content: 'MCP internal tools,protocol tools,AI assistant,server management,automation' }, + ] + - ['meta', { property: 'og:title', content: 'MCP Internal Tools Reference - 1MCP' }] + - [ + 'meta', + { + property: 'og:description', + content: 'Complete reference for MCP internal tools used by AI assistants for server management', + }, + ] +--- + +# MCP Internal Tools + +MCP internal tools are Model Context Protocol tools that enable AI assistants to discover, install, manage, and interact with MCP servers programmatically. These tools are exposed through the MCP protocol and provide comprehensive automation capabilities for server lifecycle management. + +Unlike CLI commands which are used by humans, internal tools are designed specifically for AI assistant integration and automated workflows. + +## Overview + +The internal tools are organized into three functional domains: + +- **[Discovery Tools](./internal-tools/discovery)** - Search registries and discover MCP servers +- **[Installation Tools](./internal-tools/installation)** - Install, update, and remove MCP servers +- **[Management Tools](./internal-tools/management)** - Control server operational state and configuration + +## Tool Categories + +### Discovery Tools + +Enable AI assistants to search for and discover MCP servers from various registries and sources. + +- **`mcp_search`** - Search MCP registry for servers +- **`mcp_registry_status`** - Check registry availability and health +- **`mcp_registry_info`** - Get detailed registry information +- **`mcp_registry_list`** - List available registries +- **`mcp_info`** - Get detailed server information + +### Installation Tools + +Provide complete lifecycle management for MCP server installation and removal. + +- **`mcp_install`** - Install MCP server from registry or custom source +- **`mcp_uninstall`** - Remove MCP server with backup and rollback options +- **`mcp_update`** - Update MCP server to latest or specified version + +### Management Tools + +Offer operational control over MCP servers including state management and configuration. + +- **`mcp_enable`** - Enable a disabled MCP server +- **`mcp_disable`** - Disable an MCP server without removal +- **`mcp_list`** - List MCP servers with filtering and status information +- **`mcp_status`** - Get detailed server status and health information +- **`mcp_reload`** - Reload server configuration or restart server +- **`mcp_edit`** - Edit MCP server configuration + +## Example Usage + +### AI Assistant Workflow + +Here's how an AI assistant might use these internal tools to help a user: + +#### Example 1: Setting up a Development Environment + +```json +// User: "I need to work with a PostgreSQL database and Git repository" + +[ + { + "tool": "mcp_search", + "arguments": { + "query": "postgresql database" + } + }, + { + "tool": "mcp_search", + "arguments": { + "query": "git repository" + } + }, + { + "tool": "mcp_install", + "arguments": { + "serverName": "postgres", + "version": "2.0.1" + } + }, + { + "tool": "mcp_install", + "arguments": { + "serverName": "git", + "version": "3.1.0" + } + }, + { + "tool": "mcp_list", + "arguments": { + "filter": "enabled" + } + } +] +``` + +#### Example 2: Server Health Monitoring + +```json +// AI Assistant performs routine health check + +[ + { + "tool": "mcp_list", + "arguments": {} + }, + { + "tool": "mcp_status", + "arguments": { + "serverName": "filesystem" + } + }, + { + "tool": "mcp_registry_status", + "arguments": {} + } +] +``` + +### Programmatic Integration + +#### Example 3: CI/CD Pipeline Integration + +```bash +# Deploy script using 1MCP internal tools via API +#!/bin/bash + +# Install required MCP servers for the project +echo "Installing MCP servers..." + +curl -X POST http://localhost:3050/mcp \ + -H "Content-Type: application/json" \ + -d '{ + "tool": "mcp_install", + "arguments": { + "serverName": "project-dependencies", + "version": "latest" + } + }' + +# Verify installation +curl -X POST http://localhost:3050/mcp \ + -H "Content-Type: application/json" \ + -d '{ + "tool": "mcp_list", + "arguments": { + "filter": "enabled" + } + }' +``` + +#### Example 4: Infrastructure as Code + +```json +{ + "mcp_servers": [ + { + "tool": "mcp_install", + "arguments": { + "serverName": "redis-cache", + "version": "1.2.1", + "config": { + "host": "localhost", + "port": 6379 + } + } + }, + { + "tool": "mcp_install", + "arguments": { + "serverName": "file-storage", + "version": "2.0.0", + "config": { + "rootPath": "/data/storage" + } + } + } + ] +} +``` + +## Use Cases + +### AI Assistant Automation + +AI assistants can use these tools to automatically: + +- **Discover relevant servers** for specific tasks or domains +- **Install required servers** based on user needs or project requirements +- **Manage server lifecycle** including updates, health monitoring, and troubleshooting +- **Orchestrate complex workflows** involving multiple MCP servers + +### Programmatic Server Management + +Developers can integrate these tools into: + +- **CI/CD pipelines** for automated MCP server deployment +- **Infrastructure as code** solutions for server configuration +- **Monitoring systems** for server health and performance tracking +- **Automated testing** frameworks for MCP server validation + +### Dynamic Configuration + +Tools enable dynamic server management scenarios: + +- **On-demand server installation** based on user requirements +- **Graceful server updates** with rollback capabilities +- **Health-based server failover** and recovery +- **Configuration synchronization** across environments + +## Key Features + +### Comprehensive API Coverage + +All internal tools provide complete input/output schemas with: + +- **Typed parameters** with validation and constraints +- **Structured output** with consistent data formats +- **Error handling** with detailed error information +- **Progress feedback** for long-running operations + +### Safe Operations + +Internal tools prioritize safety and reliability: + +- **Backup and restore** capabilities for destructive operations +- **Dependency validation** to prevent breaking changes +- **Rollback support** for failed operations +- **Health checks** before and after operations + +### Integration-Friendly + +Designed for seamless AI assistant integration: + +- **Semantic naming** following MCP conventions +- **Descriptive error messages** for troubleshooting +- **Progress indicators** for user feedback +- **Cross-references** between related operations + +## API Reference + +For detailed API documentation including schemas, parameters, and examples: + +- **[Discovery Tools](./internal-tools/discovery)** - Discovery domain tools and workflows +- **[Installation Tools](./internal-tools/installation)** - Installation domain tools and safety features +- **[Management Tools](./internal-tools/management)** - Management domain tools and operational control + +## Getting Started + +AI assistants typically access these tools through the MCP protocol when connected to a 1MCP instance. The tools are automatically available based on the server's capabilities and configuration. + +For CLI users, many of these capabilities are also available through the [1MCP commands](../commands/), providing human-friendly interfaces for the same operations. + +## See Also + +- [Server Management Guide](../guide/essentials/server-management) - Manual server management +- [MCP Commands Reference](../commands/mcp/) - CLI commands for server management diff --git a/docs/en/reference/internal-tools/discovery.md b/docs/en/reference/internal-tools/discovery.md new file mode 100644 index 00000000..2ca00fbc --- /dev/null +++ b/docs/en/reference/internal-tools/discovery.md @@ -0,0 +1,103 @@ +--- +title: Discovery Tools +description: MCP internal tools for discovering and searching MCP servers, registries, and server information +head: + - ['meta', { name: 'keywords', content: 'MCP discovery,server search,registry,AI assistant' }] + - ['meta', { property: 'og:title', content: 'Discovery Tools - 1MCP Internal Tools' }] + - ['meta', { property: 'og:description', content: 'MCP internal tools for server discovery and registry management' }] +--- + +# Discovery Tools + +Discovery tools enable AI assistants to find, evaluate, and gather information about MCP servers from various sources. These tools provide comprehensive search capabilities, registry management, and detailed server information retrieval. + +## Tools Overview + +### mcp_search + +Search MCP registries for servers matching specific criteria. Supports advanced filtering, categorization, and fuzzy matching to find relevant servers for any use case. + +### mcp_registry_status + +Check the availability and health of MCP registries. Provides performance metrics, uptime information, and connectivity status to ensure reliable registry access. + +### mcp_registry_info + +Get detailed information about specific MCP registries including supported features, authentication requirements, and server statistics. + +### mcp_registry_list + +List all available MCP registries with their capabilities and access requirements. Helps identify the best registry sources for different types of servers. + +### mcp_info + +Retrieve comprehensive information about specific MCP servers including capabilities, requirements, version history, and compatibility details. + +## Usage Patterns + +### Server Discovery Workflow + +AI assistants typically follow this discovery pattern: + +1. **Registry Check**: Use `mcp_registry_status` to verify registry availability +2. **Server Search**: Use `mcp_search` with relevant filters and categories +3. **Server Details**: Use `mcp_info` to get detailed information about promising servers +4. **Registry Information**: Use `mcp_registry_info` and `mcp_registry_list` to understand available sources + +### Search Strategies + +AI assistants can effectively search for servers by: + +- Using specific queries with relevant keywords and categories +- Applying filters for tags, capabilities, and compatibility +- Leveraging fuzzy matching for approximate search terms +- Sorting results by relevance, popularity, or recency + +### Registry Management + +AI assistants manage registry operations by: + +- Checking multiple registry status for reliability +- Comparing server availability across different registries +- Monitoring registry performance and response times +- Identifying the most appropriate registry for specific needs + +## AI Assistant Use Cases + +### Automated Server Discovery + +AI assistants can automatically find suitable servers by analyzing user requirements, searching with appropriate parameters, evaluating server capabilities against needs, and recommending optimal server choices. + +### Registry Health Monitoring + +AI assistants can monitor registry availability, track performance metrics over time, identify connectivity issues, and report registry problems for attention. + +### Server Evaluation + +AI assistants can evaluate servers by comparing capabilities, checking version compatibility, analyzing dependency requirements, and assessing community metrics like popularity and ratings. + +## Tool Interactions + +Discovery tools work effectively in combination: + +- **Discovery Process**: `mcp_registry_status` → `mcp_search` → `mcp_info` +- **Registry Analysis**: `mcp_registry_list` → `mcp_registry_info` → `mcp_registry_status` +- **Server Research**: `mcp_search` (with filters) → `mcp_info` (for details) +- **Health Monitoring**: Regular `mcp_registry_status` checks for reliability + +## Best Practices for AI Assistants + +1. **Check registry status** before performing searches +2. **Use specific search terms** with relevant filters +3. **Compare multiple sources** using different registries +4. **Verify server compatibility** before recommendations +5. **Monitor search performance** and adjust query complexity +6. **Cache server information** when appropriate for efficiency +7. **Use fallback registries** when primary sources are unavailable +8. **Validate search results** for relevance and accuracy + +## See Also + +- [Installation Tools](./installation) - Server lifecycle management +- [Management Tools](./management) - Server operational control +- [MCP Commands Reference](../../commands/mcp/) - CLI discovery commands diff --git a/docs/en/reference/internal-tools/index.md b/docs/en/reference/internal-tools/index.md new file mode 100644 index 00000000..d4564f6a --- /dev/null +++ b/docs/en/reference/internal-tools/index.md @@ -0,0 +1,280 @@ +--- +title: Internal Tools Overview +description: Introduction to 1MCP internal tools for AI assistant automation and server management +head: + - ['meta', { name: 'keywords', content: 'MCP internal tools,AI assistant,automation,server management' }] + - ['meta', { property: 'og:title', content: 'Internal Tools Overview - 1MCP' }] + - ['meta', { property: 'og:description', content: 'Introduction to MCP internal tools for AI assistant automation' }] +--- + +# Internal Tools Overview + +Internal tools are MCP protocol tools that enable AI assistants to programmatically manage MCP servers within the 1MCP ecosystem. These tools provide comprehensive automation capabilities for server discovery, installation, and operational management. + +## Purpose and Design + +Internal tools are specifically designed for **AI assistant integration**, not human interaction. While CLI commands provide user-friendly interfaces for server management, internal tools offer programmatic access with: + +- **Structured input/output** following MCP protocol standards +- **Comprehensive schemas** with validation and type safety +- **Atomic operations** with rollback and error handling +- **Automation-friendly** workflows and state management + +## Enabling Internal Tools + +Internal tools are disabled by default and must be explicitly enabled through CLI flags or environment variables. This ensures that only intended AI assistants can access these powerful management capabilities. + +### CLI Flags + +Enable internal tools when starting the 1MCP server: + +```bash +# Enable ALL internal tools +npx -y @1mcp/agent serve --enable-internal-tools + +# Enable specific tools by name +npx -y @1mcp/agent serve --internal-tools="search,list,status,registry" + +# Enable tools by category +npx -y @1mcp/agent serve --internal-tools="discovery,management" + +# Enable safe (read-only) tools only +npx -y @1mcp/agent serve --internal-tools="safe" +``` + +### Available Tool Categories + +- **discovery**: Registry search and server discovery tools +- **installation**: Server installation, update, and removal tools +- **management**: Server control and configuration tools +- **safe**: Read-only tools (discovery + read-only management) + +### Individual Tools + +- **search**: `mcp_search` - Search MCP registry for servers +- **list**: `mcp_list` - List MCP servers with status +- **status**: `mcp_status` - Get detailed server status +- **registry**: Registry management tools +- **install/uninstall/update**: Installation tools +- **enable/disable/edit**: Management tools + +### Security Considerations + +When enabling internal tools: + +- **Principle of Least Privilege**: Enable only the tools needed for your use case +- **Network Security**: Ensure 1MCP is accessible only to trusted AI assistants +- **Use Safe Mode**: Consider `--internal-tools="safe"` for read-only operations when possible +- **Monitor Usage**: Regularly review which tools are being used by AI assistants + +### Examples + +```bash +# Development environment - full access +npx -y @1mcp/agent serve --enable-internal-tools + +# Production environment - discovery and management only +npx -y @1mcp/agent serve --internal-tools="discovery,management" + +# Read-only monitoring setup +npx -y @1mcp/agent serve --internal-tools="safe" + +# Specific server management scenario +npx -y @1mcp/agent serve --internal-tools="search,list,status,enable,disable" +``` + +## Tool Architecture + +The internal tools system is organized into three logical domains that mirror the server lifecycle: + +```mermaid +graph TD + A[Discovery Tools] --> B[Installation Tools] + B --> C[Management Tools] + + A1[mcp_search] --> A + A2[mcp_registry_status] --> A + A3[mcp_registry_info] --> A + A4[mcp_registry_list] --> A + A5[mcp_info] --> A + + B1[mcp_install] --> B + B2[mcp_uninstall] --> B + B3[mcp_update] --> B + + C1[mcp_enable] --> C + C2[mcp_disable] --> C + C3[mcp_list] --> C + C4[mcp_status] --> C + C5[mcp_reload] --> C + C6[mcp_edit] --> C +``` + +## Workflow Patterns + +### Typical AI Assistant Workflow + +AI assistants typically follow this pattern when using internal tools: + +1. **Discovery Phase** + - Use `mcp_registry_status` to check registry availability + - Use `mcp_search` to find relevant servers + - Use `mcp_info` to get detailed server information + +2. **Installation Phase** + - Use `mcp_install` to install required servers + - Use `mcp_status` to verify installation success + - Use `mcp_list` to confirm server availability + +3. **Management Phase** + - Use `mcp_enable`/`mcp_disable` to control server state + - Use `mcp_status` for ongoing health monitoring + - Use `mcp_reload`/`mcp_edit` for configuration changes + +### Automation Workflow Example + +```javascript +// Example AI assistant workflow for setting up a development environment + +async function setupDevelopmentEnvironment() { + // 1. Discover available servers + const registryStatus = await mcp_registry_status(); + if (!registryStatus.isAvailable) { + throw new Error('Registry not available'); + } + + // 2. Search for development tools + const devTools = await mcp_search({ + query: 'development debugging tools', + category: 'development', + }); + + // 3. Install required servers + const installations = []; + for (const server of devTools.results) { + const installResult = await mcp_install({ + name: server.name, + version: server.recommendedVersion, + }); + installations.push(installResult); + } + + // 4. Verify installation + const serverList = await mcp_list(); + const installedServers = serverList.servers.filter((server) => server.status === 'running'); + + // 5. Enable servers as needed + for (const server of installedServers) { + if (server.disabled) { + await mcp_enable({ name: server.name }); + } + } + + return { + installed: installations.length, + running: installedServers.length, + servers: installedServers, + }; +} +``` + +## Key Capabilities + +### Safe Operations + +All internal tools prioritize operational safety: + +- **Transaction support** with rollback capabilities +- **Dependency validation** to prevent breaking changes +- **Health checks** before and after operations +- **Backup creation** for destructive operations +- **Atomic commits** with proper cleanup + +### Rich Feedback + +Tools provide comprehensive operational feedback: + +- **Progress indicators** for long-running operations +- **Detailed status information** including logs and metrics +- **Error context** with suggested resolutions +- **Operation history** for audit and debugging + +### Integration Features + +Designed for seamless AI assistant integration: + +- **Semantic naming** following MCP conventions +- **Consistent schemas** across all tools +- **Cross-tool compatibility** with shared data structures +- **Extensible design** for future tool additions + +## Tool Domains + +### Discovery Tools + +Focus on finding and evaluating MCP servers: + +- **Registry integration** with multiple registry sources +- **Advanced search** with filtering and categorization +- **Server information** with capabilities and requirements +- **Health monitoring** for registry services + +### Installation Tools + +Handle complete server lifecycle management: + +- **Flexible installation** from various sources (registry, git, custom) +- **Version management** with dependency resolution +- **Safe uninstallation** with backup and rollback +- **Update automation** with compatibility checking + +### Management Tools + +Provide operational control and monitoring: + +- **State management** with graceful transitions +- **Configuration editing** with validation and hot-reload +- **Health monitoring** with detailed diagnostics +- **Performance tracking** with metrics and alerts + +## Comparison with CLI Commands + +| Aspect | Internal Tools | CLI Commands | +| -------------------- | --------------------- | -------------------------- | +| **Target User** | AI assistants | Humans | +| **Interface** | MCP protocol | Command line | +| **Output Format** | Structured data | Human-readable text | +| **Error Handling** | Structured exceptions | User-friendly messages | +| **Automation** | Native support | Manual scripting required | +| **Batch Operations** | Built-in capabilities | Requires shell scripting | +| **Integration** | Direct MCP access | External process execution | + +## Best Practices + +### For AI Assistant Developers + +- **Use structured error handling** with proper exception handling +- **Implement retry logic** for transient failures +- **Cache server information** to reduce registry calls +- **Validate prerequisites** before operations +- **Monitor operation progress** and provide user feedback + +### For Tool Users + +- **Plan operations** before execution to understand dependencies +- **Use status checks** to verify operation success +- **Implement backup strategies** for critical servers +- **Monitor server health** regularly +- **Document custom configurations** for reproducibility + +## Next Steps + +- **[Discovery Tools](./discovery)** - Learn about server discovery capabilities +- **[Installation Tools](./installation)** - Understand installation and lifecycle management +- **[Management Tools](./management)** - Explore operational control features +- **[Main Reference Page](../internal-tools.md)** - Complete reference documentation + +## See Also + +- [MCP Protocol Specification](https://modelcontextprotocol.io/) - Understanding the underlying protocol +- [CLI Commands Reference](../../commands/) - Human-friendly server management alternatives diff --git a/docs/en/reference/internal-tools/installation.md b/docs/en/reference/internal-tools/installation.md new file mode 100644 index 00000000..a28e78d6 --- /dev/null +++ b/docs/en/reference/internal-tools/installation.md @@ -0,0 +1,109 @@ +--- +title: Installation Tools +description: MCP internal tools for installing, updating, and managing MCP server lifecycle +head: + - ['meta', { name: 'keywords', content: 'MCP installation,server management,lifecycle,AI assistant' }] + - ['meta', { property: 'og:title', content: 'Installation Tools - 1MCP Internal Tools' }] + - [ + 'meta', + { property: 'og:description', content: 'MCP internal tools for server installation and lifecycle management' }, + ] +--- + +# Installation Tools + +Installation tools enable AI assistants to manage the complete lifecycle of MCP servers, from initial installation through updates and removal. These tools provide flexible installation options, dependency management, and safe operation handling. + +## Tools Overview + +### mcp_install + +Install MCP servers from various sources including registries, Git repositories, or custom URLs. Supports version specification, dependency resolution, and automatic configuration. + +### mcp_uninstall + +Remove MCP servers safely with dependency checking, backup options, and cleanup of related resources. Ensures clean removal without affecting other servers. + +### mcp_update + +Update MCP servers to newer versions with compatibility checking, rollback capabilities, and migration support. Handles version conflicts and dependency updates automatically. + +## Usage Patterns + +### Server Installation Workflow + +AI assistants typically follow this installation pattern: + +1. **Discovery**: Use discovery tools to find suitable servers +2. **Installation**: Use `mcp_install` with appropriate source and version +3. **Verification**: Use management tools to confirm successful installation +4. **Configuration**: Apply necessary settings and enable the server + +### Installation Sources + +AI assistants can install servers from multiple sources: + +- **Registry Installation**: Install from official or third-party registries +- **Git Repository**: Direct installation from Git repositories +- **Custom Sources**: Installation from specific URLs or local paths +- **Version Specification**: Install specific versions or latest stable releases + +### Update Management + +AI assistants handle updates through: + +- **Compatibility Checking**: Verify version compatibility before updates +- **Dependency Resolution**: Handle dependency updates automatically +- **Rollback Support**: Revert to previous versions if issues occur +- **Migration Assistance**: Help with configuration migrations + +## AI Assistant Use Cases + +### Automated Environment Setup + +AI assistants can automatically set up complete environments by identifying required servers for specific tasks, installing servers with correct versions, resolving dependencies automatically, and configuring servers for immediate use. + +### Maintenance and Updates + +AI assistants can maintain server environments by monitoring for available updates, scheduling updates during maintenance windows, testing compatibility before applying updates, and handling rollback if issues arise. + +### Server Management + +AI assistants can manage server populations by tracking installed servers and versions, identifying unused or deprecated servers, coordinating updates across server groups, and ensuring consistent environments across deployments. + +## Tool Interactions + +Installation tools work effectively with other tool categories: + +- **Discovery to Installation**: Discovery tools → `mcp_install` → Management tools verification +- **Update Workflows**: Management tools status check → `mcp_update` → `mcp_reload` +- **Removal Process**: Management tools dependency check → `mcp_uninstall` → cleanup +- **Complete Lifecycle**: Discovery → Installation → Management → Updates → Removal + +## Best Practices for AI Assistants + +1. **Verify prerequisites** before installation attempts +2. **Use compatible versions** based on system requirements +3. **Check dependencies** to avoid conflicts +4. **Create backups** before major updates +5. **Test installations** in safe environments first +6. **Monitor installation progress** and handle errors appropriately +7. **Document custom configurations** for reproducibility +8. **Plan rollback strategies** before applying updates + +## Safety Considerations + +AI assistants should prioritize safety by: + +- Checking system compatibility before installation +- Verifying source authenticity and security +- Using appropriate version constraints +- Testing in non-production environments when possible +- Maintaining backup copies of critical configurations +- Following dependency best practices to avoid conflicts + +## See Also + +- [Discovery Tools](./discovery) - Server discovery and search +- [Management Tools](./management) - Server operational control +- [MCP Commands Reference](../../commands/mcp/) - CLI installation commands diff --git a/docs/en/reference/internal-tools/management.md b/docs/en/reference/internal-tools/management.md new file mode 100644 index 00000000..9b7836e5 --- /dev/null +++ b/docs/en/reference/internal-tools/management.md @@ -0,0 +1,110 @@ +--- +title: Management Tools +description: MCP internal tools for managing MCP server state, configuration, health monitoring, and operational control +head: + - ['meta', { name: 'keywords', content: 'MCP management,server control,monitoring,AI assistant' }] + - ['meta', { property: 'og:title', content: 'Management Tools - 1MCP Internal Tools' }] + - [ + 'meta', + { property: 'og:description', content: 'MCP internal tools for server management and operational control' }, + ] +--- + +# Management Tools + +Management tools provide comprehensive operational control over MCP servers, including state management, configuration editing, health monitoring, and performance optimization. These tools focus on providing fine-grained control and real-time visibility for AI assistants. + +## Tools Overview + +### mcp_enable + +Enable disabled MCP servers, supporting selective feature activation and dependency validation. Ensures servers meet all operational requirements before being enabled. + +### mcp_disable + +Gracefully disable MCP servers, supporting connection drainage and state preservation. Supports temporary disabling or complete service shutdown. + +### mcp_list + +List all configured MCP servers, supporting filtering by status, tags, and functionality. Provides detailed runtime information and configuration overview. + +### mcp_status + +Get detailed status information for specific servers, including health metrics, performance statistics, and diagnostic information. Supports historical status tracking and trend analysis. + +### mcp_reload + +Reload server configurations or restart servers, supporting hot reload and zero-downtime updates. Includes rollback mechanisms and configuration validation. + +### mcp_edit + +Edit MCP server configurations, providing real-time validation, schema checking, and syntax highlighting. Supports configuration templates and batch updates. + +## Usage Patterns + +### Server Lifecycle Management + +AI assistants manage server states through simple tool calls: + +- Use `mcp_enable` to activate disabled servers with validation options +- Use `mcp_disable` to gracefully shut down servers with connection drainage +- Use `mcp_status` to verify server state before and after operations +- Use `mcp_list` to discover servers and filter by status or tags + +### Configuration Management + +AI assistants manage configurations through: + +- `mcp_edit` for making configuration changes with validation +- `mcp_reload` for applying configuration updates +- Built-in backup and rollback capabilities in `mcp_edit` +- Hot reload support for zero-downtime updates + +### Health Monitoring + +AI assistants monitor server health by: + +- Using `mcp_status` with metrics and diagnostics options +- Monitoring multiple servers through `mcp_list` followed by status checks +- Analyzing performance trends and resource usage +- Identifying and responding to health issues + +## AI Assistant Use Cases + +### Server Health Monitoring + +AI assistants can maintain server health by regularly checking status across all servers, identifying unhealthy or inactive servers, and reporting issues for attention. + +### Configuration Management + +AI assistants can automate configuration tasks by applying standard configurations across server groups, validating changes before application, and using backup features for safe modifications. + +### Troubleshooting + +AI assistants can diagnose server issues by collecting status and diagnostic information, analyzing common problems like high resource usage or error rates, and providing actionable recommendations. + +## Tool Interactions + +Management tools work effectively in sequences: + +- **State Management**: `mcp_list` → `mcp_status` → `mcp_enable/disable` +- **Configuration Updates**: `mcp_status` → `mcp_edit` → `mcp_reload` +- **Health Monitoring**: `mcp_status` with metrics for ongoing monitoring +- **Targeted Operations**: `mcp_list` with filtering for specific server groups + +## Best Practices for AI Assistants + +1. **Verify prerequisites** before making changes +2. **Use status checks** to confirm operation success +3. **Handle errors gracefully** and provide clear feedback +4. **Monitor server health** before and after operations +5. **Create backups** using mcp_edit options before configuration changes +6. **Use batch operations** efficiently for multiple server management +7. **Implement retry logic** for transient failures +8. **Validate configurations** before applying changes + +## See Also + +- [Discovery Tools](./discovery) - Server discovery and evaluation +- [Installation Tools](./installation) - Server lifecycle management +- [MCP Commands Reference](../../commands/mcp/) - CLI server management commands diff --git a/docs/public/llms-en.txt b/docs/public/llms-en.txt new file mode 100644 index 00000000..dc8d0fda --- /dev/null +++ b/docs/public/llms-en.txt @@ -0,0 +1,36 @@ +# 1MCP Agent - English Documentation + +> Comprehensive English documentation for 1MCP, covering installation, configuration, server management, and advanced deployment scenarios. + +## Essential Guides + +- [Installation & Setup](/en/guide/installation.md): Complete setup guide for binary and npm installations +- [Quick Start Guide](/en/guide/quick-start.md): 5-minute setup walkthrough with examples +- [Getting Started](/en/guide/getting-started.md): Complete setup and configuration guide +- [Server Management](/en/guide/essentials/server-management.md): Add, configure, and manage MCP servers +- [Basic Configuration](/en/guide/essentials/configuration.md): Core configuration options and setup + +## CLI Reference + +- [MCP Commands](/en/commands/mcp/): Server management commands (add, remove, list, install, uninstall) +- [App Commands](/en/commands/app/): Backup, restore, and application management +- [Preset Commands](/en/commands/preset/): Configuration preset management +- [Registry Commands](/en/commands/registry/): MCP server registry integration +- [Proxy & Serve Commands](/en/commands/serve.md, /en/commands/proxy.md): HTTP proxy configuration and serving + +## Advanced Configuration + +- [Architecture Overview](/en/reference/architecture.md): System design and component interaction +- [Security Best Practices](/en/reference/security.md): Authentication, authorization, and hardening +- [Performance Optimization](/en/guide/advanced/performance.md): Scaling and optimization techniques +- [Client Integration](/en/guide/integrations/): Setup for various AI assistants and tools +- [Enterprise Setup](/en/guide/advanced/enterprise.md): Enterprise deployment configuration +- [Advanced Authentication](/en/guide/advanced/authentication.md): OAuth and advanced security setup + +## Optional + +- [Internal Tools](/en/reference/internal-tools/): Built-in discovery, installation, and management tools +- [Health Check](/en/reference/health-check.md): Health monitoring and status endpoints +- [MCP Servers](/en/reference/mcp-servers.md): MCP server configuration reference +- [Feature Comparison](/en/reference/feature-comparison.md): Version and feature comparisons +- [Core Features](/en/guide/essentials/core-features.md): Overview of main 1MCP capabilities \ No newline at end of file diff --git a/docs/public/llms-full.txt b/docs/public/llms-full.txt new file mode 100644 index 00000000..fdf93bd4 --- /dev/null +++ b/docs/public/llms-full.txt @@ -0,0 +1,377 @@ +# 1MCP Agent - Complete Documentation + +> 1MCP is a Model Context Protocol proxy that aggregates capabilities from multiple MCP servers into a unified interface, enabling AI assistants to connect to multiple tools and services through a single connection. This comprehensive documentation covers installation, configuration, server management, security, and advanced deployment scenarios. + +## Overview + +1MCP Agent serves as a centralized proxy for Model Context Protocol (MCP) servers, allowing AI assistants to seamlessly connect to multiple tools, databases, and services through a single connection point. It supports both HTTP/SSE and STDIO transports, provides comprehensive server management capabilities, and includes advanced features like server filtering, preset management, and health monitoring. + +## Getting Started + +### Installation Options + +#### Binary Installation +Download the latest release from GitHub releases and add to your system PATH. + +#### NPM Installation +```bash +npm install -g @1mcp/agent +``` + +#### Development Setup +```bash +git clone https://github.com/1mcp-app/agent.git +cd agent +pnpm install +pnpm build +``` + +### Quick Start Configuration + +Create a basic configuration file to add MCP servers: +```bash +1mcp mcp add filesystem -- npx -y @modelcontextprotocol/server-filesystem /tmp +``` + +Start the proxy server: +```bash +1mcp serve --port 3051 +``` + +## Core Features + +### Server Management + +#### Adding Servers +```bash +# Add MCP servers from the registry +1mcp mcp add filesystem +1mcp mcp add database + +# Add custom servers with commands +1mcp mcp add custom-server -- npx -y @your/custom-server +``` + +#### Server Operations +- **Add/Remove**: Dynamically add or remove MCP servers +- **Enable/Disable**: Temporarily enable or disable servers without removing configuration +- **Install/Uninstall**: Install packages from the MCP registry or uninstall them +- **Update**: Update servers to latest versions +- **Status**: Check server health and connectivity status + +#### Server Configuration +- **Command-based servers**: Execute external processes with custom commands +- **Registry-based servers**: Install and manage from MCP registry +- **Tag-based filtering**: Organize servers with tags for selective access +- **Environment variables**: Configure server-specific environment settings + +### Application Management + +#### Backup and Restore +```bash +# Backup current configuration +1mcp app backup /path/to/backup.json + +# Restore from backup +1mcp app restore /path/to/backup.json +``` + +#### Consolidation +- **App Discovery**: Automatically discover and consolidate MCP applications +- **Configuration Merging**: Merge multiple configurations into unified setup + +### Preset Management + +#### Configuration Presets +```bash +# Create new preset +1mcp preset create development + +# Edit preset configuration +1mcp preset edit development + +# Test preset configuration +1mcp preset test development + +# Select active preset +1mcp preset select development +``` + +#### Preset Features +- **Environment-specific configurations**: Separate presets for development, staging, production +- **Server groups**: Organize servers into logical groups +- **Configuration testing**: Validate preset configurations before deployment + +### Registry Integration + +#### MCP Registry +```bash +# Search available MCP servers +1mcp registry search filesystem +1mcp registry search database + +# Install from registry +1mcp mcp install @modelcontextprotocol/server-filesystem +``` + +## CLI Commands Reference + +### MCP Commands + +#### Server Management +- `1mcp mcp add [command]`: Add new MCP server +- `1mcp mcp remove `: Remove configured server +- `1mcp mcp list`: List all configured servers +- `1mcp mcp status [name]`: Check server status and health +- `1mcp mcp enable `: Enable a disabled server +- `1mcp mcp disable `: Disable a server temporarily + +#### Package Management +- `1mcp mcp install `: Install package from MCP registry +- `1mcp mcp uninstall `: Uninstall and remove server +- `1mcp mcp update `: Update server to latest version +- `1mcp mcp search `: Search MCP registry + +### App Commands + +#### Configuration Management +- `1mcp app backup `: Backup current configuration +- `1mcp app restore `: Restore configuration from backup +- `1mcp app status`: Show application status and information + +#### Discovery and Consolidation +- `1mcp app discover `: Discover MCP applications in directory +- `1mcp app consolidate`: Consolidate discovered applications +- `1mcp app list`: List discovered applications + +### Preset Commands + +#### Preset Management +- `1mcp preset create `: Create new configuration preset +- `1mcp preset delete `: Delete existing preset +- `1mcp preset edit `: Edit preset configuration +- `1mcp preset list`: List all available presets +- `1mcp preset select `: Select active preset +- `1mcp preset show [name]`: Show preset details +- `1mcp preset test `: Test preset configuration + +### Registry Commands + +#### Registry Operations +- `1mcp registry search `: Search MCP registry for servers +- `1mcp registry info `: Get detailed package information + +### Serve and Proxy Commands + +#### Server Operations +- `1mcp serve`: Start HTTP proxy server +- `1mcp serve --port `: Specify custom port +- `1mcp serve --host `: Bind to specific host +- `1mcp proxy`: Start in proxy mode + +## Advanced Configuration + +### Configuration Structure + +#### Global Configuration +Configuration is stored in JSON format with the following main sections: +- **servers**: MCP server configurations +- **proxy**: HTTP proxy settings +- **logging**: Log configuration +- **auth**: Authentication settings + +#### Server Configuration +Each server configuration includes: +- **command**: Server execution command +- **args**: Command arguments +- **env**: Environment variables +- **tags**: Server tags for filtering +- **disabled**: Enable/disable flag + +### Environment Variables + +#### Core Configuration +- `ONE_MCP_CONFIG_DIR`: Configuration directory path +- `ONE_MCP_LOG_LEVEL`: Logging level (debug, info, warn, error) +- `ONE_MCP_PORT`: Default server port (default: 3051) +- `ONE_MCP_HOST`: Default server host (default: localhost) + +#### Development Variables +- `ONE_MCP_LOG_FILE`: Log file path +- `ONE_MCP_ENABLE_AUTH`: Enable authentication +- `ONE_MCP_ENABLE_ASYNC_LOADING`: Enable async server loading + +### Performance Optimization + +#### Server Loading +- **Async Loading**: Orchestrate slow-starting servers gracefully +- **Health Monitoring**: Continuous server health checks +- **Connection Management**: Efficient connection pooling and reuse + +#### Resource Management +- **Memory Optimization**: Streaming for large responses +- **Process Management**: Proper cleanup of child processes +- **Resource Monitoring**: Track resource usage and limits + +### Developer Tools +- **IDE Integration**: Support for various development environments +- **HTTP Transport**: Web-based client connections +- **Tag-based Access**: Filter servers based on client requirements +- **Real-time Updates**: Dynamic capability updates + +## Architecture + +### System Components + +#### Core Components +- **ServerManager**: MCP server lifecycle management and health monitoring +- **TransportFactory**: Protocol-specific transport creation (HTTP, STDIO) +- **CapabilitiesManager**: Dynamic capability aggregation across servers +- **McpConfigManager**: Configuration management with hot-reload support + +#### Transport Layer +- **HTTP/SSE Transport**: Multi-client support via Server-Sent Events +- **STDIO Transport**: Direct MCP protocol communication +- **Connection Management**: Connection pooling and multiplexing + +### Design Patterns + +#### Singleton Pattern +- **ServerManager**: Centralized server instance management +- **McpConfigManager**: Global configuration management +- **AgentConfigManager**: Application-wide settings + +#### Factory Pattern +- **TransportFactory**: Protocol-specific transport instantiation +- **Configuration Parser**: Format-specific configuration parsing + +## Security Features + +### Access Control +- **Tag-based Filtering**: Control server access based on client tags +- **Scope-based Authorization**: Fine-grained permission control +- **Environment Variable Protection**: Secure handling of sensitive environment data + +### Configuration Security +- **Validation**: Schema-based configuration validation +- **Hot Reload Security**: Safe configuration updates without service interruption +- **Process Isolation**: Isolated server processes for security + +## Deployment + +### Development Environment +```bash +# Start development server with hot reload +pnpm dev + +# Run tests +pnpm test + +# Build for production +pnpm build +``` + +### Production Deployment + +#### Docker Deployment +```dockerfile +FROM node:22-alpine +WORKDIR /app +COPY package*.json ./ +RUN npm install -g @1mcp/agent +EXPOSE 3051 +CMD ["1mcp", "serve", "--port", "3051"] +``` + +#### Service Configuration +- **Process Management**: Use PM2 or similar for process management +- **Reverse Proxy**: Nginx or Apache reverse proxy configuration +- **SSL/TLS**: HTTPS termination for secure connections +- **Monitoring**: Health check endpoints and logging + +## Monitoring and Observability + +### Health Monitoring +- **Health Endpoints**: Built-in health check endpoints +- **Server Status**: Real-time server connectivity monitoring +- **Performance Metrics**: Resource usage and response times + +### Logging +- **Structured Logging**: Winston-based logging with metadata +- **Log Levels**: Configurable log levels (debug, info, warn, error) +- **Conditional Logging**: Performance-optimized conditional logging +- **Log Rotation**: Automatic log file rotation and archival + +## Troubleshooting + +### Common Issues + +#### Connection Problems +- Server startup failures and configuration errors +- Network connectivity and firewall issues +- Port conflicts and binding problems + +#### Configuration Issues +- Invalid JSON syntax and missing required fields +- Environment variable conflicts and file permissions +- Server command and argument configuration errors + +### Debug Tools + +#### Built-in Diagnostics +- **Status Commands**: `1mcp app status`, `1mcp mcp status` +- **Configuration Validation**: Check configuration syntax and validity +- **Health Checks**: Verify server connectivity and responsiveness + +#### Debug Logging +```bash +# Enable debug logging +ONE_MCP_LOG_LEVEL=debug 1mcp serve + +# Log to specific file +ONE_MCP_LOG_FILE=./debug.log 1mcp serve +``` + +## Reference Documentation + +### Technical References +- **Architecture**: Detailed system design and component interaction +- **Security**: Security implementation details and best practices +- **Internal Tools**: Discovery, installation, and management tools +- **Health Check**: Health monitoring endpoint documentation +- **MCP Servers**: MCP server configuration and management +- **Feature Comparison**: Version differences and capability comparisons + +### Configuration Reference +- **Core Features**: Detailed feature documentation +- **Essentials**: Core configuration and management +- **Advanced Topics**: Enterprise, performance, and security configurations +- **Integration Guides**: Client integration and setup instructions + +## Contributing + +### Development Workflow +1. Fork the repository +2. Create feature branch from main +3. Implement changes with comprehensive tests +4. Update documentation as needed +5. Submit pull request for review + +### Code Quality Standards +- **TypeScript**: Strict type safety and comprehensive type definitions +- **Testing**: High test coverage with unit and integration tests +- **Code Style**: ESLint and Prettier for consistent formatting +- **Documentation**: Comprehensive API documentation and examples + +## Support and Community + +### Getting Help +- **GitHub Issues**: Report bugs and request features +- **Documentation**: Comprehensive guides and reference documentation +- **Community**: Discussion forums and community support + +### Resources +- **Repository**: https://github.com/1mcp-app/agent +- **Documentation**: https://docs.1mcp.app +- **MCP Specification**: Model Context Protocol documentation +- **Registry**: MCP server registry and ecosystem diff --git a/docs/public/llms-zh.txt b/docs/public/llms-zh.txt new file mode 100644 index 00000000..c04175fd --- /dev/null +++ b/docs/public/llms-zh.txt @@ -0,0 +1,36 @@ +# 1MCP Agent - 中文文档 + +> 1MCP 代理的完整中文文档，包含安装、配置、服务器管理和高级部署场景。 + +## 基础指南 + +- [安装与设置](/zh/guide/installation.md): 二进制和 npm 安装的完整设置指南 +- [快速开始](/zh/guide/quick-start.md): 5分钟设置 walkthrough 及示例 +- [入门指南](/zh/guide/getting-started.md): 完整的设置和配置指南 +- [服务器管理](/zh/guide/essentials/server-management.md): 添加、配置和管理 MCP 服务器 +- [基础配置](/zh/guide/essentials/configuration.md): 核心配置选项和设置 + +## 命令行参考 + +- [MCP 命令](/zh/commands/mcp/): 服务器管理命令（添加、移除、列表、安装、卸载） +- [应用命令](/zh/commands/app/): 备份、恢复和应用管理 +- [预设命令](/zh/commands/preset/): 配置预设管理 +- [注册表命令](/zh/commands/registry/): MCP 服务器注册表集成 +- [代理和服务命令](/zh/commands/serve.md, /zh/commands/proxy.md): HTTP 代理配置和服务 + +## 高级配置 + +- [架构概述](/zh/reference/architecture.md): 系统设计和组件交互 +- [安全最佳实践](/zh/reference/security.md): 身份验证、授权和加固 +- [性能优化](/zh/guide/advanced/performance.md): 扩展和优化技术 +- [客户端集成](/zh/guide/integrations/): 各种 AI 助手和工具的设置 +- [企业设置](/zh/guide/advanced/enterprise.md): 企业部署配置 +- [高级身份验证](/zh/guide/advanced/authentication.md): OAuth 和高级安全设置 + +## 可选 + +- [内部工具](/zh/reference/internal-tools/): 内置发现、安装和管理工具 +- [健康检查](/zh/reference/health-check.md): 健康监控和状态端点 +- [MCP 服务器](/zh/reference/mcp-servers.md): MCP 服务器配置参考 +- [功能比较](/zh/reference/feature-comparison.md): 版本和功能比较 +- [核心功能](/zh/guide/essentials/core-features.md): 主要 1MCP 功能概述 \ No newline at end of file diff --git a/docs/public/llms.txt b/docs/public/llms.txt new file mode 100644 index 00000000..78d9ac6e --- /dev/null +++ b/docs/public/llms.txt @@ -0,0 +1,41 @@ +# 1MCP Agent + +> 1MCP is a Model Context Protocol proxy that aggregates capabilities from multiple MCP servers into a unified interface, enabling AI assistants to connect to multiple tools and services through a single connection. + +## Getting Started + +- [Installation Guide](/guide/installation.md): Set up 1MCP using binary or npm installation +- [5-Minute Quick Start](/guide/quick-start.md): Get up and running with basic configuration +- [Getting Started](/guide/getting-started.md): Complete setup and configuration guide +- [Basic Configuration](/guide/essentials/configuration.md): Core configuration options and setup + +## Core Features + +- [Server Management](/guide/essentials/server-management.md): Add, remove, and manage MCP servers +- [CLI Commands Reference](/commands/): Complete command-line interface documentation +- [Core Features](/guide/essentials/core-features.md): Overview of main 1MCP capabilities +- [Features Overview](/guide/features.md): Complete feature list and descriptions + +## Client Integration + +- [Claude Desktop Integration](/guide/integrations/claude-desktop.md): Connect with Claude Desktop +- [Developer Tools Integration](/guide/integrations/developer-tools.md): Integration with development environments +- [App Consolidation](/guide/integrations/app-consolidation.md): Application consolidation guide +- [Codex Integration](/guide/integrations/codex.md): Codex integration setup + +## Advanced Topics + +- [Architecture](/reference/architecture.md): System design and component overview +- [Security](/reference/security.md): Security implementation and best practices +- [Performance](/guide/advanced/performance.md): Optimization and scaling guidance +- [Reverse Proxy](/guide/advanced/reverse-proxy.md): Production deployment options +- [Enterprise Setup](/guide/advanced/enterprise.md): Enterprise deployment guide +- [Authentication](/guide/advanced/authentication.md): Advanced authentication setup + +## Optional + +- [Internal Tools](/reference/internal-tools.md): Built-in discovery and management tools +- [Health Check](/reference/health-check.md): Health monitoring endpoints +- [MCP Servers](/reference/mcp-servers.md): MCP server configuration reference +- [Feature Comparison](/reference/feature-comparison.md): Version and feature comparisons +- [Contributing](https://github.com/1mcp-app/agent/blob/main/CONTRIBUTING.md): Development contribution guidelines \ No newline at end of file diff --git a/docs/zh/commands/mcp/install.md b/docs/zh/commands/mcp/install.md new file mode 100644 index 00000000..23e4ec8e --- /dev/null +++ b/docs/zh/commands/mcp/install.md @@ -0,0 +1,217 @@ +--- +title: mcp install +description: 从 1MCP 注册表安装 MCP 服务器 +head: + - ['meta', { name: 'keywords', content: 'MCP 安装,注册表服务器安装,交互式向导,服务器发现' }] + - ['meta', { property: 'og:title', content: '1MCP 安装命令 - 注册表服务器安装' }] + - ['meta', { property: 'og:description', content: '使用交互式向导和版本管理从注册表安装 MCP 服务器。' }] +--- + +# mcp install + +从 1MCP 注册表安装 MCP 服务器，具有自动依赖解析和版本管理功能。安装命令提供交互式向导引导安装和按名称直接安装服务器。 + +> **注意**：这是向配置中添加 MCP 服务器推荐的方式。对于手动配置，请参阅 [add 命令](add.md)。 + +## 命令语法 + +启动交互式安装向导： + +```bash +npx -y @1mcp/agent mcp install +``` + +按名称从注册表安装服务器： + +```bash +npx -y @1mcp/agent mcp install +``` + +安装特定版本： + +```bash +npx -y @1mcp/agent mcp install @ +``` + +预览安装而不进行更改： + +```bash +npx -y @1mcp/agent mcp install --dry-run +``` + +强制重新安装： + +```bash +npx -y @1mcp/agent mcp install --force +``` + +## 参数 + +- **``** (可选) + - 服务器名称或 name@version 进行安装。可以包含完整的注册表 ID（例如：`io.github.user/filesystem`）。 + - **必需**: 否 + +## 全局选项 + +此命令支持所有全局选项： + +- **`--config, -c <路径>`** - 指定配置文件路径 +- **`--config-dir, -d <路径>`** - 配置目录路径 + +## 命令特定选项 + +- **`--interactive, -i`** + - 启动交互式安装向导。当未提供服务器名称时，这是默认选项。 + +- **`--force`** + - 即使服务器已存在也强制安装。覆盖现有配置。 + +- **`--dry-run`** + - 显示将要安装的内容，而不对配置进行任何更改。 + +- **`--verbose, -v`** + - 显示详细的安装信息。 + +## 示例 + +### 基本服务器安装 + +安装文件系统服务器的最新版本： + +```bash +npx -y @1mcp/agent mcp install filesystem +``` + +安装特定版本： + +```bash +npx -y @1mcp/agent mcp install filesystem@1.2.0 +``` + +### 交互式向导安装 + +启动交互式向导来浏览和安装服务器： + +```bash +npx -y @1mcp/agent mcp install --interactive +``` + +向导将指导您完成以下步骤： + +1. **服务器发现** - 按类别浏览可用服务器 +2. **版本选择** - 选择兼容版本 +3. **配置** - 设置服务器特定选项 +4. **安装** - 确认并安装及其依赖 + +### 安装预览 + +预览将要安装的内容而不进行更改： + +```bash +npx -y @1mcp/agent mcp install filesystem --dry-run + +# 输出: +# 📦 安装预览: filesystem@1.2.0 +# +# 服务器: filesystem - 文件系统访问和管理 +# 版本: 1.2.0 +# 类别: 系统 +# 标签: filesystem, files, local +# +# 依赖: 无 +# 配置: 将提示输入根目录 +# +# 使用 --verbose 获取详细信息 +``` + +### 强制重新安装 + +替换现有服务器配置： + +```bash +npx -y @1mcp/agent mcp install filesystem --force +``` + +### 详细安装 + +查看包含依赖解析的详细安装过程： + +```bash +npx -y @1mcp/agent mcp install airtable --verbose + +# 输出: +# 🔍 解析 airtable@2.1.0 的依赖... +# ✓ 依赖检查完成 +# 📥 下载服务器元数据... +# ✓ 验证服务器配置 +# ⚙️ 生成配置... +# ✓ 服务器成功安装为 'airtable' +``` + +## 交互式工作流程 + +当使用 `--interactive` 或不带参数运行时，安装命令会启动引导向导，帮助您： + +1. **搜索** 按名称或浏览类别查找服务器 +2. **选择** 服务器并查看其功能 +3. **选择** 版本（稳定版与最新版） +4. **配置** 服务器特定参数 +5. **确认** 安装 + +## 注册表功能 + +- **服务器发现**：搜索和浏览可用的 MCP 服务器 +- **版本管理**：安装特定版本并检查兼容性 +- **依赖解析**：自动处理所需的依赖 +- **安全验证**：验证服务器完整性和真实性 + +## 配置输出 + +已安装的服务器会添加到您的 `mcp.json` 配置中，包含注册表元数据： + +```json +{ + "mcpServers": { + "filesystem": { + "command": "npx", + "args": ["-y", "@modelcontextprotocol/server-filesystem", "/home/user"], + "tags": ["filesystem", "files", "local"], + "_registry": { + "name": "filesystem", + "version": "1.2.0", + "installedAt": "2024-01-15T10:30:00Z", + "source": "1mcp-registry" + } + } + } +} +``` + +## 错误处理 + +安装命令为常见场景提供有用的错误消息： + +```bash +# 服务器未找到 +npx -y @1mcp/agent mcp install nonexistent-server +# 错误：在注册表中找不到服务器 'nonexistent-server' +# 建议：filesystem, git, database, search + +# 版本不可用 +npx -y @1mcp/agent mcp install filesystem@99.99.99 +# 错误：'filesystem' 的版本 99.99.99 不可用 +# 可用版本：1.2.0, 1.1.0, 1.0.0 + +# 已安装 +npx -y @1mcp/agent mcp install filesystem +# 错误：服务器 'filesystem' 已安装 +# 使用 --force 重新安装或使用 mcp update 升级 +``` + +## 另请参阅 + +- **[注册表搜索](../registry/search.md)** - 在注册表中搜索可用服务器 +- **[mcp uninstall](uninstall.md)** - 移除已安装的服务器 +- **[mcp update](update.md)** - 更新已安装的服务器 +- **[服务器管理指南](../../guide/essentials/server-management.md)** - 完整的服务器管理概述 +- **[注册表命令](../registry/)** - 完整的注册表命令文档 diff --git a/docs/zh/commands/mcp/search.md b/docs/zh/commands/mcp/search.md new file mode 100644 index 00000000..4a58d5f0 --- /dev/null +++ b/docs/zh/commands/mcp/search.md @@ -0,0 +1,59 @@ +--- +title: MCP 搜索命令 - 注册表服务器发现 +description: 搜索 MCP 注册表中可用的服务器。此命令是 'registry search' 的别名，提供快速访问服务器发现功能。 +head: + - ['meta', { name: 'keywords', content: 'MCP 搜索,注册表服务器发现,服务器浏览,筛选' }] + - ['meta', { property: 'og:title', content: '1MCP 搜索命令 - 注册表服务器发现' }] + - ['meta', { property: 'og:description', content: '搜索 MCP 注册表中可用的服务器，支持筛选选项。' }] +--- + +# mcp search + +搜索 MCP 注册表中可用的服务器。此命令是 `registry search` 命令的**便利别名**，选项有限。如需高级筛选和选项，请直接使用[注册表搜索](../registry/search.md)。 + +## 概述 + +按查询搜索服务器： + +```bash +npx -y @1mcp/agent mcp search +``` + +浏览所有可用服务器： + +```bash +npx -y @1mcp/agent mcp search +``` + +## 参数 + +`` (可选) +: 用于匹配服务器名称、描述和标签的搜索查询字符串。 + +## 限制 + +由于这是 `registry search` 的别名，它只支持基本的搜索功能。高级筛选选项如 `--status`、`--type`、`--transport` 和 `--format` 仅在完整的[注册表搜索](../registry/search.md)命令中可用。 + +## 示例 + +### 基本搜索 + +搜索与数据库相关的服务器： + +```bash +npx -y @1mcp/agent mcp search database +``` + +### 浏览所有服务器 + +列出所有可用的服务器： + +```bash +npx -y @1mcp/agent mcp search +``` + +## 另请参阅 + +- **[注册表搜索](../registry/search.md)** - 具有高级选项的完整注册表搜索命令 +- **[注册表命令](../registry/)** - 完整的注册表命令文档 +- **[mcp install](install.md)** - 安装通过搜索找到的服务器 diff --git a/docs/zh/commands/mcp/uninstall.md b/docs/zh/commands/mcp/uninstall.md new file mode 100644 index 00000000..7e410f30 --- /dev/null +++ b/docs/zh/commands/mcp/uninstall.md @@ -0,0 +1,266 @@ +--- +title: MCP 卸载命令 - 安全的服务器移除 +description: 安全地卸载 MCP 服务器，自动创建备份并检查依赖。移除服务器并清理配置。 +head: + - ['meta', { name: 'keywords', content: 'MCP 卸载,服务器移除,备份创建,安全删除' }] + - ['meta', { property: 'og:title', content: '1MCP 卸载命令 - 安全的服务器移除' }] + - ['meta', { property: 'og:description', content: '安全地卸载 MCP 服务器，自动创建备份并检查依赖。' }] +--- + +# mcp uninstall + +安全地从您的配置中移除 MCP 服务器，自动创建备份并验证依赖。卸载命令确保安全移除并具有回滚功能。 + +## 概述 + +带确认和备份地移除服务器： + +```bash +npx -y @1mcp/agent mcp uninstall +``` + +跳过确认提示： + +```bash +npx -y @1mcp/agent mcp uninstall --force +``` + +移除而不创建备份： + +```bash +npx -y @1mcp/agent mcp uninstall --backup=false +``` + +## 参数 + +`` (必需) +: 要卸载的服务器名称。必须是您配置中现有的服务器。 + +## 全局选项 + +- **`--config, -c <路径>`** - 指定配置文件路径 +- **`--config-dir, -d <路径>`** - 配置目录路径 + +## 命令特定选项 + +- **`--force, -y`** + - 跳过确认提示并继续卸载 + - **默认**：`false` + +- **`--backup`** + - 移除前创建备份 + - **默认**：`true` + +- **`--remove-config`** + - 从 mcp.json 中移除服务器配置 + - **默认**：`true` + +- **`--verbose, -v`** + - 显示详细的卸载信息 + - **默认**：`false` + +## 示例 + +### 基本服务器移除 + +带确认和备份地移除服务器： + +```bash +npx -y @1mcp/agent mcp uninstall filesystem + +# 输出: +# 🔄 准备卸载 'filesystem'... +# ℹ️ 服务器 'filesystem' 当前正在运行 +# ℹ️ 服务器具有以下功能：file_read, file_write, list_directory +# ℹ️ 没有其他服务器依赖于 'filesystem' +# +# ⚠️ 这将： +# • 停止 'filesystem' 服务器 +# • 从 mcp.json 中移除服务器配置 +# • 在以下位置创建备份：~/.config/1mcp/backups/mcp-20240115-103000.json +# +# 继续？(y/N): y +# +# ✓ 服务器 'filesystem' 成功停止 +# ✓ 配置已从 mcp.json 中移除 +# ✓ 备份已创建：~/.config/1mcp/backups/mcp-20240115-103000.json +# ✅ 卸载成功完成 +``` + +### 强制卸载 + +跳过确认提示： + +```bash +npx -y @1mcp/agent mcp uninstall filesystem --force + +# 输出: +# 🔄 正在卸载 'filesystem'... +# ✓ 服务器已停止 +# ✓ 配置已移除 +# ✓ 备份已创建 +# ✅ 卸载完成 +``` + +### 无备份卸载 + +移除服务器而不创建备份（不推荐）： + +```bash +npx -y @1mcp/agent mcp uninstall test-server --backup=false + +# 输出: +# ⚠️ 跳过备份创建 +# 🔄 正在卸载 'test-server'... +# ✓ 服务器已移除 +# ✅ 无备份完成卸载 +``` + +### 详细卸载 + +查看详细的卸载过程： + +```bash +npx -y @1mcp/agent mcp uninstall database --verbose + +# 输出: +# 🔍 正在分析服务器 'database'... +# • 在 mcp.json 中找到配置 +# • 服务器当前正在运行（PID：12345） +# • 依赖：0 个服务器依赖此服务器 +# • 备份位置：~/.config/1mcp/backups/mcp-20240115-103500.json +# +# 🛡️ 安全检查通过 +# 🔄 继续卸载... +# • 优雅地停止服务器进程 +# • 从活动服务器列表中移除 +# • 更新 mcp.json 配置 +# • 创建配置备份 +# +# ✅ 卸载成功完成 +``` + +## 安全功能 + +### 依赖检查 + +卸载命令在移除前检查依赖： + +```bash +npx -y @1mcp/agent mcp uninstall shared-storage + +# 输出: +# ❌ 无法卸载 'shared-storage' +# +# 以下服务器依赖于 'shared-storage': +# • file-processor（使用 shared-storage 进行临时文件存储） +# • backup-service（使用 shared-storage 进行备份存储） +# +# 请先卸载依赖服务器或使用 --force 继续。 +``` + +### 自动备份 + +默认情况下，卸载命令会创建带时间戳的备份： + +```bash +# 备份位置示例： +~/.config/1mcp/backups/mcp-20240115-103000.json +~/.config/1mcp/backups/mcp-20240115-103500.json +``` + +备份文件包括： + +- 完整的 mcp.json 配置 +- 服务器元数据和安装信息 +- 用于轻松识别的时间戳 + +### 优雅关闭 + +服务器在移除前会被优雅地停止： + +```bash +# 优雅关闭流程： +1. 向服务器进程发送 SIGTERM 信号 +2. 等待最多 10 秒进行优雅关闭 +3. 如果仍在运行则发送 SIGKILL +4. 验证进程终止 +5. 从服务器管理器中移除 +``` + +## 错误处理 + +常见错误场景和解决方案： + +```bash +# 服务器未找到 +npx -y @1mcp/agent mcp uninstall nonexistent-server +# 错误：在配置中找不到服务器 'nonexistent-server' +# 使用 'mcp list' 查看可用服务器 + +# 服务器依赖 +npx -y @1mcp/agent mcp uninstall shared-server --force +# 警告：正在移除有依赖的服务器 +# 依赖将受到影响：file-processor, backup-service + +# 权限问题 +npx -y @1mcp/agent mcp uninstall system-server +# 错误：停止服务器进程时权限被拒绝 +# 请尝试使用提升的权限或检查服务器状态 +``` + +## 备份恢复 + +需要时从备份恢复： + +```bash +# 列出可用备份 +ls ~/.config/1mcp/backups/ + +# 从备份恢复 +cp ~/.config/1mcp/backups/mcp-20240115-103000.json ~/.config/1mcp/mcp.json + +# 重新加载配置 +npx -y @1mcp/agent mcp reload +``` + +## 清理选项 + +卸载命令提供几个清理选项： + +### 仅移除配置 + +```bash +npx -y @1mcp/agent mcp uninstall server-name --remove-config +# 从 mcp.json 中移除但如果服务器处于活动状态则保持运行 +``` + +### 自定义备份位置 + +```bash +ONE_MCP_CONFIG_DIR=/custom/path npx -y @1mcp/agent mcp uninstall server-name +# 在自定义配置目录中创建备份 +``` + +## 与注册表的集成 + +对于注册表安装的服务器，卸载还会： + +```bash +# 移除注册表元数据 +npx -y @1mcp/agent mcp uninstall filesystem + +# 移除的注册表元数据： +# • 安装时间戳 +# • 源注册表信息 +# • 版本跟踪数据 +# • 更新通知 +``` + +## 另请参阅 + +- **[mcp install](install.md)** - 从注册表安装服务器 +- **[mcp disable](enable-disable.md)** - 临时禁用服务器 +- **[mcp list](list.md)** - 列出已安装的服务器 +- **[服务器管理指南](../../guide/essentials/server-management.md)** - 完整的服务器管理概述 +- **[配置参考](../../reference/mcp-servers.md)** - 配置文件结构 diff --git a/docs/zh/commands/registry/index.md b/docs/zh/commands/registry/index.md new file mode 100644 index 00000000..6a1a465e --- /dev/null +++ b/docs/zh/commands/registry/index.md @@ -0,0 +1,294 @@ +--- +title: 注册表命令 - MCP 服务器发现和管理 +description: 1MCP 注册表命令的完整指南，用于服务器发现、安装、版本管理和依赖解析。 +head: + - ['meta', { name: 'keywords', content: 'MCP 注册表,服务器发现,版本管理,依赖解析' }] + - ['meta', { property: 'og:title', content: '1MCP 注册表命令 - 服务器发现和管理' }] + - [ + 'meta', + { + property: 'og:description', + content: '通过 1MCP 注册表发现、安装和管理 MCP 服务器，具有版本控制和依赖管理功能。', + }, + ] +--- + +# 注册表命令 + +1MCP 注册表为 MCP 服务器提供集中式服务器发现、版本管理和依赖解析。注册表命令使您能够搜索服务器、查看详细信息、检查版本并管理服务器安装。 + +> **快速开始**：使用 `npx @1mcp/agent mcp install <服务器名称>` 进行简化安装。 + +## 概述 + +1MCP 注册表是一个集中式存储库，它： + +- **发现**跨类别的可用 MCP 服务器 +- **管理**版本控制和兼容性信息 +- **自动解析**依赖 +- **验证**服务器完整性和安全性 +- **提供**详细的服务器元数据和文档 + +## 可用命令 + +### 服务器发现 + +- **[registry search](search.md)** - 按名称、类别或标签搜索服务器 + +## 注册表工作流程 + +### 1. 发现 + +找到符合您需求的服务器： + +```bash +# 按类别搜索 +npx -y @1mcp/agent registry search --category=filesystem + +# 按功能搜索 +npx -y @1mcp/agent registry search "database" + +# 浏览所有服务器 +npx -y @1mcp/agent registry search +``` + +### 2. 信息收集 + +获取服务器的详细信息： + +```bash +# 查看服务器详情 +npx -y @1mcp/agent registry show filesystem + +# 检查可用版本 +npx -y @1mcp/agent registry versions filesystem + +# 查看依赖和要求 +npx -y @1mcp/agent registry show postgresql --deps +``` + +### 3. 安装 + +安装服务器并自动解析依赖： + +```bash +# 安装最新版本 +npx -y @1mcp/agent mcp install filesystem + +# 安装特定版本 +npx -y @1mcp/agent mcp install filesystem@1.2.0 + +# 使用交互式向导安装 +npx -y @1mcp/agent mcp install --interactive +``` + +### 4. 管理 + +保持服务器更新和管理： + +```bash +# 检查更新 +npx -y @1mcp/agent registry updates + +# 更新特定服务器 +npx -y @1mcp/agent mcp update filesystem + +# 移除服务器 +npx -y @1mcp/agent mcp uninstall filesystem +``` + +## 服务器类别 + +注册表将服务器组织成功能性类别： + +### 系统和文件管理 + +- **文件系统** - 文件系统访问和操作 +- **数据库** - 数据库连接和操作 +- **存储** - 云存储和对象管理 +- **备份** - 数据备份和恢复工具 + +### 开发工具 + +- **Git** - 版本控制和仓库操作 +- **构建** - 构建系统和编译工具 +- **测试** - 测试框架和实用程序 +- **调试** - 调试和分析工具 + +### 网络和网络 + +- **HTTP** - HTTP 客户端和 API 工具 +- **搜索** - 网络搜索和信息检索 +- **抓取** - 网络抓取和数据提取 +- **API** - API 集成和管理 + +### 数据处理 + +- **分析** - 数据分析和报告 +- **机器学习** - 机器学习模型服务和训练 +- **ETL** - 数据转换和管道 +- **可视化** - 数据可视化工具 + +### 通信 + +- **电子邮件** - 电子邮件发送和管理 +- **聊天** - 消息传递和通信平台 +- **日历** - 日历和计划工具 +- **通知** - 警报和通知系统 + +## 服务器元数据 + +注册表中的每个服务器都包含全面的元数据： + +```json +{ + "name": "filesystem", + "displayName": "File System Server", + "description": "文件系统访问和管理功能", + "version": "1.2.0", + "category": "System", + "tags": ["filesystem", "files", "local", "storage"], + "maintainer": "Model Context Protocol Team", + "license": "MIT", + "homepage": "https://github.com/modelcontextprotocol/servers", + "repository": "https://github.com/modelcontextprotocol/servers/tree/main/src/filesystem", + "documentation": "https://docs.modelcontextprotocol.io/servers/filesystem", + "dependencies": [], + "engines": { + "node": ">=14.0.0" + }, + "platforms": ["linux", "darwin", "win32"], + "transport": ["stdio"], + "capabilities": { + "tools": ["read_file", "write_file", "list_directory", "create_directory"], + "resources": ["file://*"] + }, + "security": { + "trusted": true, + "sandboxed": false, + "permissions": ["filesystem"] + }, + "installation": { + "npm": "@modelcontextprotocol/server-filesystem", + "command": "npx", + "args": ["-y", "@modelcontextprotocol/server-filesystem"] + }, + "changelog": "https://github.com/modelcontextprotocol/servers/blob/main/CHANGELOG.md" +} +``` + +## 版本管理 + +注册表遵循语义版本控制（SemVer）： + +- **主版本** - 破坏性更改 +- **次版本** - 新功能（向后兼容） +- **修订版本** - 错误修复（向后兼容） + +### 版本选择 + +```bash +# 安装最新的稳定版本 +npx -y @1mcp/agent mcp install filesystem + +# 安装特定的主版本 +npx -y @1mcp/agent mcp install filesystem@1 + +# 安装特定的次版本 +npx -y @1mcp/agent mcp install filesystem@1.2 + +# 安装确切版本 +npx -y @1mcp/agent mcp install filesystem@1.2.0 + +# 安装预发布版本 +npx -y @1mcp/agent mcp install filesystem@2.0.0-beta.1 +``` + +## 安全和信任 + +注册表包含安全验证： + +- **受信任的来源** - 已验证的维护者和存储库 +- **漏洞扫描** - 自动安全检查 +- **依赖审核** - 包依赖安全分析 +- **代码审查** - 社区审查流程 + +## 私有注册表 + +用于企业和私有服务器管理： + +```bash +# 配置私有注册表 +npx -y @1mcp/agent registry config --add private.registry.com + +# 与私有注册表进行身份验证 +npx -y @1mcp/agent registry login private.registry.com + +# 搜索私有注册表 +npx -y @1mcp/agent registry search --registry=private.registry.com +``` + +## 与 MCP 命令的集成 + +注册表命令与 MCP 命令无缝集成： + +```bash +# 这些是等效的： +npx -y @1mcp/agent registry search filesystem +npx -y @1mcp/agent mcp install --search filesystem + +# 从注册表搜索结果安装 +npx -y @1mcp/agent registry search database | head -5 | xargs -I {} npx -y @1mcp/agent mcp install {} + +# 检查所有已安装服务器的更新 +npx -y @1mcp/agent registry updates --installed +``` + +## 缓存管理 + +注册表操作使用本地缓存以提高性能： + +```bash +# 清除注册表缓存 +npx -y @1mcp/agent registry cache --clear + +# 强制刷新服务器信息 +npx -y @1mcp/agent registry show filesystem --refresh + +# 设置缓存过期 +npx -y @1mcp/agent registry config --cache-expire=1h +``` + +## 最佳实践 + +### 服务器选择 + +1. **检查兼容性** - 确保服务器匹配您的环境 +2. **审查依赖** - 了解所需的依赖 +3. **阅读文档** - 审查服务器功能和限制 +4. **检查维护** - 优先选择积极维护的服务器 +5. **在开发中测试** - 在非生产环境中验证服务器 + +### 版本管理 + +1. **使用特定版本** - 为生产稳定性固定版本 +2. **测试更新** - 在升级前验证新版本 +3. **监控变更日志** - 跟踪更改和弃用 +4. **备份配置** - 保留工作配置的备份 +5. **回滚计划** - 准备降级策略 + +### 安全性 + +1. **验证来源** - 仅使用来自受信任维护者的服务器 +2. **审查权限** - 了解服务器访问要求 +3. **定期更新** - 为安全补丁保持服务器更新 +4. **隔离环境** - 为不同环境使用单独的配置 +5. **审核依赖** - 监控依赖安全更新 + +## 另请参阅 + +- **[mcp install](../mcp/install.md)** - 从注册表安装服务器 +- **[mcp uninstall](../mcp/uninstall.md)** - 移除已安装的服务器 +- **[服务器管理指南](../../guide/essentials/server-management.md)** - 完整的服务器管理 +- **[配置参考](../../reference/mcp-servers.md)** - 配置详细信息 +- **[入门指南](../../guide/getting-started.md)** - 初始设置说明 diff --git a/docs/zh/commands/registry/search.md b/docs/zh/commands/registry/search.md new file mode 100644 index 00000000..2cdd44c8 --- /dev/null +++ b/docs/zh/commands/registry/search.md @@ -0,0 +1,436 @@ +--- +title: 注册表搜索命令 - 服务器发现 +description: 按名称、类别、标签或功能在 1MCP 注册表中搜索 MCP 服务器。筛选结果并找到符合您特定要求的服务器。 +head: + - ['meta', { name: 'keywords', content: 'MCP 注册表搜索,服务器发现,筛选,服务器查找' }] + - ['meta', { property: 'og:title', content: '1MCP 注册表搜索命令 - 服务器发现' }] + - ['meta', { property: 'og:description', content: '在 1MCP 注册表中搜索 MCP 服务器，具有高级筛选和发现功能。' }] +--- + +# registry search + +使用各种筛选条件和标准在 1MCP 注册表中搜索 MCP 服务器。按名称、类别、标签或功能查找服务器，支持高级筛选选项。 + +## 概述 + +按名称或关键字搜索服务器： + +```bash +npx -y @1mcp/agent registry search +``` + +浏览所有可用服务器： + +```bash +npx -y @1mcp/agent registry search +``` + +按传输类型筛选： + +```bash +npx -y @1mcp/agent registry search --transport=stdio +``` + +使用多个标准的高级筛选： + +```bash +npx -y @1mcp/agent registry search database --type=npm --format=json +``` + +## 参数 + +`` (可选) +: 要与服务器名称、描述和标签匹配的搜索查询字符串。支持部分匹配和模糊搜索。 + +## 全局选项 + +- **`--config, -c <路径>`** - 指定配置文件路径 +- **`--config-dir, -d <路径>`** - 配置目录路径 + +## 命令特定选项 + +- **`--status <状态>`** + - 按服务器状态筛选 + - **选择**：`active`、`archived`、`deprecated`、`all` + - **默认**：`active` + +- **`--type <类型>`** + - 按包注册表类型筛选 + - **选择**：`npm`、`pypi`、`docker` + +- **`--transport <传输>`** + - 按传输方式筛选 + - **选择**：`stdio`、`sse`、`http` + +- **`--limit <数字>`** + - 返回的最大结果数 + - **默认**：`20` + - **最大值**：`100` + +- **`--cursor <字符串>`** + - 用于检索下一页结果的分页游标 + +- **`--format <格式>`** + - 搜索结果的输出格式 + - **选择**：`table`、`list`、`json` + - **默认**：`table` + +## 示例 + +### 基本搜索 + +搜索与文件系统相关的服务器： + +```bash +npx -y @1mcp/agent registry search filesystem + +# 输出: +# 🔍 搜索结果："filesystem" +# +# 名称 | 类别 | 版本 | 描述 +# ----------------- | --------- | ----- | ----------------------------------------- +# filesystem | 系统 | 1.2.0 | 文件系统访问和管理 +# ftp | 网络 | 1.0.1 | FTP/SFTP 文件操作 +# cloud-storage | 存储 | 2.1.0 | 云存储集成 (S3, GCS) +# backup | 系统 | 1.5.2 | 文件备份和同步 +# +# 找到 4 个结果（显示 4 个，共 4 个） +``` + +### 按传输方式筛选 + +查找使用 stdio 传输的服务器： + +```bash +npx -y @1mcp/agent registry search --transport=stdio + +# 输出: +# 🗃️ 数据库服务器 +# +# 名称 | 维护者 | 版本 | 下载量 | 描述 +# ----------------- | ------------------ | ----- | ------- | ------------------------- +# postgresql | MCP 团队 | 2.0.1 | 15.2k | PostgreSQL 数据库操作 +# mongodb | MongoDB MCP | 1.3.0 | 8.7k | MongoDB 数据库访问 +# mysql | MySQL 社区 | 1.8.2 | 12.1k | MySQL 数据库连接 +# redis | Redis 实验室 | 1.2.1 | 9.4k | Redis 缓存操作 +# sqlite | SQLite 团队 | 2.1.0 | 18.3k | SQLite 数据库管理 +# +# 找到 5 个结果 +``` + +### 标签筛选 + +搜索具有特定标签的服务器： + +```bash +npx -y @1mcp/agent registry search --tag=api --tag=rest + +# 输出: +# 🔍 标记为：api, rest 的服务器 +# +# 名称 | 类别 | 版本 | 描述 +# ----------------- | --------- | ----- | ----------------------------------------- +# http-client | 网络 | 1.5.0 | HTTP/REST API 客户端 +# api-gateway | 开发 | 1.2.1 | API 网关和管理 +# rest-tools | 开发 | 1.0.3 | REST API 开发工具 +# web-scraping | Web | 2.0.1 | REST API 的网络抓取 +# +# 找到 4 个结果 +``` + +### 高级筛选 + +结合多个筛选条件获得精确结果： + +```bash +npx -y @1mcp/agent registry search \ + --category=development \ + --platform=linux \ + --transport=stdio \ + --trusted \ + --sort=popularity \ + --limit=5 + +# 输出: +# 🔍 开发服务器 (Linux, stdio, 受信任) +# +# 名称 | 版本 | 下载量 | 描述 +# ----------------- | ----- | ------- | ----------------------------------------- +# git | 3.1.0 | 25.4k | Git 仓库操作 +# docker | 2.0.1 | 18.7k | Docker 容器管理 +# npm | 1.8.0 | 14.2k | Node.js 包管理 +# python | 2.2.1 | 16.9k | Python 开发工具 +# terraform | 1.5.0 | 9.8k | Terraform 基础设施 +# +# 找到 5 个结果（共 23 个） +``` + +### 已安装服务器 + +仅显示您已安装的服务器： + +```bash +npx -y @1mcp/agent registry search --installed + +# 输出: +# 📦 已安装服务器 +# +# 名称 | 已安装 | 最新 | 状态 | 描述 +# ----------------- | ------- | ----- | -------- | ------------------------- +# filesystem | 1.2.0 | 1.2.1 | ⬆️ 更新 | 文件系统访问 +# git | 3.1.0 | 3.1.0 | ✓ 当前 | Git 操作 +# search | 1.0.2 | 1.1.0 | ⬆️ 更新 | 网络搜索功能 +# +# 已安装 3 个服务器，2 个有可用更新 +``` + +### 有更新可用的服务器 + +查找可以更新的服务器： + +```bash +npx -y @1mcp/agent registry search --updates + +# 输出: +# 🔄 可用更新 +# +# 服务器 | 当前 | 最新 | 类型 | 更改 +# ------------ | ------ | ----- | -------- | ------------------------ +# filesystem | 1.2.0 | 1.2.1 | 补丁 | 错误修复，性能 +# search | 1.0.2 | 1.1.0 | 次要 | 新功能，API +# database | 2.0.1 | 3.0.0 | 主要 | 破坏性更改，新 API +# +# 3 个更新可用 +``` + +### JSON 输出 + +获取机器可读的结果： + +```bash +npx -y @1mcp/agent registry search database --output=json + +# 输出: +# { +# "query": "database", +# "total": 5, +# "results": [ +# { +# "name": "postgresql", +# "displayName": "PostgreSQL Server", +# "description": "PostgreSQL database operations and queries", +# "version": "2.0.1", +# "category": "Database", +# "tags": ["database", "postgresql", "sql"], +# "maintainer": "MCP Team", +# "downloads": 15200, +# "trustLevel": "verified", +# "platforms": ["linux", "darwin", "win32"], +# "transport": ["stdio"], +# "lastUpdated": "2024-01-10T15:30:00Z" +# } +# ] +# } +``` + +### 详细输出 + +显示全面的服务器信息： + +```bash +npx -y @1mcp/agent registry search git --detailed --limit=1 + +# 输出: +# 🔍 详细信息：git +# +# Git 仓库操作服务器 +# ================ +# +# 版本：3.1.0 +# 类别：开发 +# 维护者：MCP 团队 +# 许可证：MIT +# +# 描述： +# 提供包括提交、分支、合并和文件历史管理在内的 Git 仓库操作。 +# 支持本地和远程仓库。 +# +# 功能： +# • 工具：git_status, git_add, git_commit, git_push, git_pull, git_branch +# • 资源：仓库文件，Git 历史 +# +# 要求： +# • Git 命令行工具 +# • 仓库文件的读取访问权限 +# • 仓库修改的写入权限 +# +# 平台：Linux、macOS、Windows +# 传输：stdio +# 下载量：25,400 +# 最后更新：2024-01-12 +# +# 安装： +# npx -y @1mcp/agent mcp install git +``` + +## 搜索语法 + +### 查询格式 + +搜索查询支持灵活匹配： + +```bash +# 精确名称匹配 +registry search filesystem + +# 部分名称匹配 +registry search file + +# 描述匹配 +registry search "file system" + +# 标签匹配 +registry search storage + +# 模糊匹配 +registry search flsystm # 匹配 "filesystem" +``` + +### 特殊操作符 + +使用特殊操作符进行高级搜索： + +```bash +# 精确短语匹配 +registry search "file system access" + +# 排除术语 +registry search database --not=mysql + +# 通配符匹配 +registry search py* # 匹配 python、pytorch 等 + +# 正则表达式 +registry search --regex="^(git|svn|hg)$" +``` + +## 类别和标签 + +### 可用类别 + +- **系统** - 文件系统、备份、实用程序 +- **数据库** - 数据库服务器和客户端 +- **开发** - 构建工具、版本控制 +- **Web** - HTTP 客户端、网络抓取 +- **网络** - 网络协议、API +- **存储** - 云存储、对象存储 +- **通信** - 电子邮件、聊天、通知 +- **数据处理** - 分析、机器学习、ETL +- **安全** - 身份验证、加密 +- **监控** - 日志、指标、警报 + +### 常用标签 + +- **传输**：stdio、http、sse +- **平台**：linux、darwin、win32、web +- **功能**：api、cli、gui、batch +- **语言**：python、javascript、go、rust +- **环境**：development、production、testing +- **安全**：trusted、verified、sandboxed + +## 排序和分页 + +### 排序选项 + +```bash +# 按受欢迎程度排序（下载量最多） +registry search --sort=popularity + +# 按最近更新排序 +registry search --sort=updated + +# 按名称排序（字母顺序） +registry search --sort=name + +# 按创建日期排序 +registry search --sort=created + +# 按下载次数排序 +registry search --sort=downloads +``` + +### 分页 + +控制结果显示： + +```bash +# 限制结果 +registry search --limit=10 + +# 跳过前 N 个结果 +registry search --offset=20 + +# 显示所有结果（最多 100 个） +registry search --limit=100 +``` + +## 注册表缓存 + +搜索结果被缓存以提高性能： + +```bash +# 强制刷新缓存 +registry search --refresh + +# 检查缓存状态 +registry status --cache + +# 清除缓存 +registry cache --clear +``` + +## 集成示例 + +### 管道安装 + +搜索和安装服务器： + +```bash +# 搜索并安装第一个结果 +registry search database --limit=1 --output=json | \ + jq -r '.results[0].name' | \ + xargs npx -y @1mcp/agent mcp install + +# 安装所有数据库服务器 +registry search --category=database --output=list | \ + xargs -n1 npx -y @1mcp/agent mcp install +``` + +### 更新检查自动化 + +在脚本中检查更新： + +```bash +#!/bin/bash +# 检查有更新可用的服务器 +updates=$(registry search --updates --output=json) +count=$(echo "$updates" | jq '.total') + +if [ "$count" -gt 0 ]; then + echo "发现 $count 个可用更新：" + echo "$updates" | jq -r '.results[] | " • \(.name): \(.current) → \(.latest)"' + + # 询问用户是否要更新 + read -p "更新所有服务器？(y/N): " -n 1 -r + echo + if [[ $REPLY =~ ^[Yy]$ ]]; then + registry search --updates --output=list | \ + xargs -n1 npx -y @1mcp/agent mcp update + fi +fi +``` + +## 另请参阅 + +- **[mcp install](../mcp/install.md)** - 从搜索结果安装服务器 +- **[服务器管理指南](../../guide/essentials/server-management.md)** - 服务器管理概述 diff --git a/docs/zh/guide/essentials/configuration.md b/docs/zh/guide/essentials/configuration.md index 86004e48..e1822f99 100644 --- a/docs/zh/guide/essentials/configuration.md +++ b/docs/zh/guide/essentials/configuration.md @@ -55,6 +55,8 @@ head: | `--session-persist-interval` | `ONE_MCP_SESSION_PERSIST_INTERVAL` | 会话持久化间隔（分钟）（数字） | 5 | | `--session-background-flush` | `ONE_MCP_SESSION_BACKGROUND_FLUSH` | 会话后台刷新间隔（秒）（数字） | 60 | | `--enable-client-notifications` | `ONE_MCP_ENABLE_CLIENT_NOTIFICATIONS` | 启用实时客户端通知（布尔值） | true | +| `--enable-internal-tools` | `ONE_MCP_ENABLE_INTERNAL_TOOLS` | 为 AI 助手启用所有 MCP 内部工具（布尔值） | false | +| `--internal-tools` | `ONE_MCP_INTERNAL_TOOLS` | 启用特定的内部工具类别（discovery,installation,management,safe） | | | `--health-info-level` | `ONE_MCP_HEALTH_INFO_LEVEL` | 健康端点信息详细级别（"full"、"basic"、"minimal"） | "minimal" | | `--log-level` | `ONE_MCP_LOG_LEVEL` | 设置日志级别（"debug"、"info"、"warn"、"error"） | "info" | | `--log-file` | `ONE_MCP_LOG_FILE` | 除控制台外还将日志写入文件（仅对 stdio 传输禁用控制台日志记录） | | @@ -260,6 +262,50 @@ npx -y @1mcp/agent --tag-filter "web and api and not test" ONE_MCP_TAG_FILTER="network+api" npx -y @1mcp/agent ``` +### 内部工具选项 + +控制为 AI 助手暴露的 MCP 内部工具。 + +**`--enable-internal-tools`** + +- **用途**：为 AI 助手启用所有 MCP 内部工具 +- **默认值**：`false` +- **环境变量**：`ONE_MCP_ENABLE_INTERNAL_TOOLS` + +**`--internal-tools <类别>`** + +- **用途**：启用特定的内部工具类别 +- **值**：逗号分隔的类别：`discovery,installation,management,safe` +- **默认值**：未启用任何类别 +- **环境变量**：`ONE_MCP_INTERNAL_TOOLS` + +**类别说明**： + +- `discovery` - 用于发现 MCP 服务器的工具（mcp*search, mcp_registry*\*） +- `installation` - 用于安装/更新/移除服务器的工具（mcp_install, mcp_update, mcp_uninstall） +- `management` - 用于管理服务器生命周期的工具（mcp_enable, mcp_disable, mcp_list, mcp_status, mcp_reload, mcp_edit） +- `safe` - 仅限只读工具（discovery 和 management 的子集） + +**示例**： + +```bash +# 启用所有内部工具 +npx -y @1mcp/agent --enable-internal-tools + +# 仅启用发现和管理工具 +npx -y @1mcp/agent --internal-tools "discovery,management" + +# 仅启用安全（只读）工具 +npx -y @1mcp/agent --internal-tools "safe" + +# 环境变量 +ONE_MCP_ENABLE_INTERNAL_TOOLS=true npx -y @1mcp/agent + +ONE_MCP_INTERNAL_TOOLS="discovery,management" npx -y @1mcp/agent +``` + +**重要提示**：内部工具与 CLI 命令不同。CLI 命令是为人类用户设计的，而内部工具是 MCP 协议工具，AI 助手可以用来自动化服务器管理任务。有关可用内部工具的详细信息，请参阅**[内部工具参考](../../reference/internal-tools.md)**。 + ### 性能选项 控制性能和资源使用行为。 diff --git a/docs/zh/guide/essentials/server-management.md b/docs/zh/guide/essentials/server-management.md index dbef882c..62806456 100644 --- a/docs/zh/guide/essentials/server-management.md +++ b/docs/zh/guide/essentials/server-management.md @@ -1,15 +1,100 @@ --- -title: 服务器管理指南 - 传输类型和最佳实践 -description: 了解如何在 1MCP 中管理 MCP 服务器。涵盖 STDIO 和 HTTP 传输、配置最佳实践和生命周期管理。 +title: 服务器管理指南 - 基于注册表的安装和配置 +description: 学习如何使用基于注册表的方法在 1MCP 中管理 MCP 服务器，包括服务器发现、安装和生命周期管理。 head: - - ['meta', { name: 'keywords', content: 'MCP 服务器管理,传输类型,STDIO 传输,HTTP 传输' }] - - ['meta', { property: 'og:title', content: '1MCP 服务器管理指南' }] - - ['meta', { property: 'og:description', content: '在 1MCP 中管理 MCP 服务器的完整指南。传输类型和最佳实践。' }] + - ['meta', { name: 'keywords', content: 'MCP 服务器管理,注册表安装,服务器发现,生命周期管理' }] + - ['meta', { property: 'og:title', content: '1MCP 服务器管理指南 - 基于注册表的方法' }] + - ['meta', { property: 'og:description', content: '使用基于注册表的安装和配置在 1MCP 中管理 MCP 服务器的完整指南。' }] --- # 服务器管理指南 -本指南详细概述了在您的 1MCP 实例中管理 MCP 服务器。它涵盖了传输类型、配置最佳实践和高级管理工作流程。 +本指南提供了在您的 1MCP 实例中使用推荐的基于注册表的方法管理 MCP 服务器的全面概述，包括服务器发现、安装和生命周期管理。 + +## 基于注册表的工作流程（推荐） + +1MCP 注册表提供了一个用于发现、安装和管理 MCP 服务器的集中式存储库，具有自动依赖解析和版本管理功能。这是推荐的服务器管理方法。 + +### 快速开始 + +从注册表安装您的第一个服务器： + +```bash +# 搜索可用的服务器 +npx -y @1mcp/agent registry search --category=filesystem + +# 安装文件系统服务器 +npx -y @1mcp/agent mcp install filesystem + +# 或使用交互式向导 +npx -y @1mcp/agent mcp wizard +``` + +### 注册表工作流程 + +1. **发现** - 找到符合您需求的服务器 +2. **选择** - 选择具有版本兼容性的服务器 +3. **安装** - 自动依赖解析和设置 +4. **配置** - 服务器特定的自定义 +5. **管理** - 更新、移除和生命周期控制 + +### 注册表优势 + +- **服务器发现** - 浏览和搜索数百个 MCP 服务器 +- **版本管理** - 安装具有兼容性检查的特定版本 +- **依赖解析** - 自动安装所需依赖项 +- **安全验证** - 具有完整性检查的已验证服务器 +- **更新管理** - 具有更改跟踪的简便更新 +- **交互式安装** - 使用配置向导进行引导设置 + +### 安装方法 + +#### 直接安装 + +按名称从注册表安装服务器： + +```bash +# 安装最新版本 +npx -y @1mcp/agent mcp install filesystem + +# 安装特定版本 +npx -y @1mcp/agent mcp install filesystem@1.2.0 + +# 带配置安装 +npx -y @1mcp/agent mcp install git --repository /path/to/project +``` + +#### 交互式向导 + +启动配置向导进行引导安装： + +```bash +# 启动交互式向导 +npx -y @1mcp/agent mcp wizard + +# 使用预定义模板启动 +npx -y @1mcp/agent mcp wizard --template development +``` + +向导提供： + +- 按类别浏览服务器 +- 分步配置 +- 兼容性检查 +- 最佳实践建议 + +#### 搜索和安装 + +搜索注册表并从结果中安装： + +```bash +# 搜索数据库服务器 +npx -y @1mcp/agent registry search database + +# 安装搜索结果 +npx -y @1mcp/agent registry search database --limit=3 --output=list | \ + xargs -n1 npx -y @1mcp/agent mcp install +``` ## 传输类型 @@ -48,65 +133,109 @@ npx -y @1mcp/agent mcp add remote-api --type=http --url="https://mcp.example.com **主要功能**： - **远程访问**：连接到本地网络或互联网上的服务器。 -- **自定义标头**：为身份验证或其他目的添加自定义 HTTP 标头。 +- **自定义标头**：添加自定义 HTTP 标头用于身份验证或其他目的。 - **连接池**：高效管理到远程服务器的连接。 ### SSE 传输（已弃用） -服务器发送事件是一种已弃用的传输类型。建议改用 HTTP 传输。 +Server-Sent Events 是已弃用的传输类型。建议改用 HTTP 传输。 + +## Server Configuration Details + +Each server you define in 1MCP has a set of common configuration options: + +- **Name**: A unique, human-readable name for the server (e.g., `my-git-server`). +- **Transport**: The transport type (`stdio` or `http`). +- **Command/URL**: The command to execute for `stdio` transports, or the URL for `http` transports. +- **Arguments**: An array of command-line arguments for `stdio` servers. +- **Environment**: Key-value pairs of environment variables for `stdio` servers. +- **Tags**: A list of tags for organizing and filtering servers. +- **Timeout**: A connection timeout in milliseconds. +- **Enabled/Disabled**: A flag to enable or disable the server without deleting its configuration. -## 服务器配置详细信息 +## Server Management Workflow + +### Registry-Based Workflow (Recommended) + +The modern workflow using the registry provides automatic dependency resolution and version management: + +1. **Discover Servers**: Search the registry for servers that meet your needs. + + ```bash + # Search for development servers + npx -y @1mcp/agent registry search --category=development + + # Browse all available servers + npx -y @1mcp/agent mcp wizard + ``` -您在 1MCP 中定义的每个服务器都有一组通用的配置选项： +2. **Install Servers**: Install servers with automatic configuration. -- **名称**：服务器的唯一、人类可读的名称（例如 `my-git-server`）。 -- **传输**：传输类型（`stdio` 或 `http`）。 -- **命令/URL**：为 `stdio` 传输执行的命令，或为 `http` 传输执行的 URL。 -- **参数**：`stdio` 服务器的命令行参数数组。 -- **环境**：`stdio` 服务器的环境变量键值对。 -- **标签**：用于组织和筛选服务器的标签列表。 -- **超时**：连接超时（以毫秒为单位）。 -- **启用/禁用**：一个标志，用于启用或禁用服务器，而无需删除其配置。 + ```bash + # Install the filesystem server + npx -y @1mcp/agent mcp install filesystem -## 服务器管理工作流程 + # Install specific version + npx -y @1mcp/agent mcp install git@1.2.0 + ``` -管理服务器的典型工作流程如下所示： +3. **Verify Installation**: Check that servers are properly installed and running. -1. **添加服务器**：向您的 1MCP 实例添加新服务器。 ```bash - # 添加本地 git 服务器 - npx -y @1mcp/agent mcp add git-main --type=stdio --command="mcp-server-git" --args="--repository ." + npx -y @1mcp/agent mcp list + npx -y @1mcp/agent mcp status filesystem ``` -2. **验证配置**：列出您的服务器并检查新服务器的状态。 + +4. **Manage Updates**: Keep servers updated with latest versions. + ```bash - ONE_MCP_LOG_LEVEL=debug npx -y @1mcp/agent mcp list - npx -y @1mcp/agent mcp status git-main + # Check for available updates + npx -y @1mcp/agent registry search --updates + + # Update specific server + npx -y @1mcp/agent mcp update filesystem ``` -3. **根据需要更新**：修改服务器的配置。例如，添加一个标签。 + +5. **Manage Lifecycle**: Enable, disable, or remove servers as needed. + ```bash - npx -y @1mcp/agent mcp update git-main --tags=source-control,project-a + # Temporarily disable + npx -y @1mcp/agent mcp disable filesystem + + # Re-enable + npx -y @1mcp/agent mcp enable filesystem + + # Remove with backup + npx -y @1mcp/agent mcp uninstall filesystem ``` -4. **管理其生命周期**：如果您需要暂时禁用服务器，可以在不丢失其配置的情况下执行此操作。 + +### Manual Configuration Workflow (Advanced) + +For custom servers not available in the registry: + +1. **Add Server Manually**: Configure server details manually. + ```bash - npx -y @1mcp/agent mcp disable git-main - # ...稍后... - npx -y @1mcp/agent mcp enable git-main + npx -y @1mcp/agent mcp add custom-server --type=stdio --command="node server.js" ``` -5. **完成后删除**：如果您不再需要该服务器，可以永久删除它。 + +2. **Configure Settings**: Set server-specific options. ```bash - npx -y @1mcp/agent mcp remove git-main + npx -y @1mcp/agent mcp update custom-server --tags=custom,experimental --args="--port=3000" ``` -## 最佳实践 +The registry-based approach is recommended for most users, with manual configuration reserved for custom or proprietary servers. + +## Best Practices -### 配置 +### Configuration -- **使用描述性名称**：为您的服务器提供清晰、描述性的名称。 -- **使用标签进行组织**：应用一致的标记策略，以轻松筛选和管理您的服务器。常见的标签类别包括环境（`dev`、`prod`）、功能（`database`、`files`）和优先级（`critical`、`optional`）。 -- **设置适当的超时**：根据服务器的预期响应能力配置超时。本地服务器的超时时间可以比远程服务器短。 +- **Use Descriptive Names**: Give your servers clear, descriptive names. +- **Use Tags for Organization**: Apply a consistent tagging strategy to easily filter and manage your servers. Common tag categories include environment (`dev`, `prod`), function (`database`, `files`), and priority (`critical`, `optional`). +- **Set Appropriate Timeouts**: Configure timeouts based on the expected responsiveness of the server. Local servers can have shorter timeouts than remote ones. -### 安全 +### Security -- **验证服务器来源**：仅添加来自受信任来源的 MCP 服务器。 -- **管理机密**：使用环境变量将 API 密钥等机密传递给您的服务器。避免在配置中对它们进行硬编码。 -- **限制权限**：以最低要求的权限运行 `stdio` 服务器。 +- **Validate Server Sources**: Only add MCP servers from trusted sources. +- **Manage Secrets**: Use environment variables to pass secrets like API keys to your servers. Avoid hardcoding them in your configuration. +- **Limit Permissions**: Run `stdio` servers with the minimum required permissions. diff --git a/docs/zh/guide/features.md b/docs/zh/guide/features.md index 4a1072bc..0024d26d 100644 --- a/docs/zh/guide/features.md +++ b/docs/zh/guide/features.md @@ -13,20 +13,21 @@ head: ## 🚀 快速发现（选择您的路径） -- **👋 我是 1MCP 的新手** → [核心功能](/guide/essentials/core-features) -- **🔒 我需要安全** → [安全与访问控制](/guide/advanced/security) -- **⚡ 我想要性能** → [性能与可靠性](/guide/advanced/performance) -- **🏢 我运行生产系统** → [企业版与运维](/guide/advanced/enterprise) -- **🔧 我是开发人员** → [开发者与集成](/guide/integrations/developer-tools) -- **🔗 我想要整合应用** → [应用整合](/guide/integrations/app-consolidation) -- **🖥️ 我使用 Claude Desktop** → [Claude Desktop 集成](/guide/integrations/claude-desktop) -- **⚙️ 我需要服务器管理** → [服务器管理](/guide/essentials/server-management) -- **🏷️ 我想要服务器过滤** → [服务器过滤](/guide/advanced/server-filtering) -- **⚡ 我需要快速启动** → [快速启动](/guide/advanced/fast-startup) +- **👋 我是 1MCP 的新手** → [核心功能](/zh/guide/essentials/core-features) +- **🔒 我需要安全** → [安全与访问控制](/zh/guide/advanced/security) +- **⚡ 我想要性能** → [性能与可靠性](/zh/guide/advanced/performance) +- **🏢 我运行生产系统** → [企业版与运维](/zh/guide/advanced/enterprise) +- **🔧 我是开发人员** → [开发者与集成](/zh/guide/integrations/developer-tools) +- **🔗 我想要整合应用** → [应用整合](/zh/guide/integrations/app-consolidation) +- **🖥️ 我使用 Claude Desktop** → [Claude Desktop 集成](/zh/guide/integrations/claude-desktop) +- **⚙️ 我需要服务器管理** → [服务器管理](/zh/guide/essentials/server-management) +- **🏷️ 我想要服务器过滤** → [服务器过滤](/zh/guide/advanced/server-filtering) +- **🤖 我需要 AI 自动化** → [AI 助手内部工具](/zh/reference/internal-tools) +- **⚡ 我需要快速启动** → [快速启动](/zh/guide/advanced/fast-startup) --- -## 🌟 [核心功能](/guide/essentials/core-features) +## 🌟 [核心功能](/zh/guide/essentials/core-features) 开箱即用的基础功能，适用于每个用户： @@ -38,7 +39,7 @@ head: --- -## 🔒 [安全与访问控制](/guide/advanced/security) +## 🔒 [安全与访问控制](/zh/guide/advanced/security) 具有细粒度权限的企业级安全： @@ -50,7 +51,7 @@ head: --- -## ⚡ [性能与可靠性](/guide/advanced/performance) +## ⚡ [性能与可靠性](/zh/guide/advanced/performance) 为生产而构建，具备智能恢复功能： @@ -62,7 +63,7 @@ head: --- -## 🏢 [企业版与运维](/guide/advanced/enterprise) +## 🏢 [企业版与运维](/zh/guide/advanced/enterprise) 生产就绪的部署和运营功能： @@ -76,7 +77,7 @@ head: --- -## 🔧 [开发者与集成](/guide/integrations/developer-tools) +## 🔧 [开发者与集成](/zh/guide/integrations/developer-tools) 开发者友好的 API 和集成工具： @@ -88,7 +89,7 @@ head: --- -## 🔗 [应用整合](/guide/integrations/app-consolidation) +## 🔗 [应用整合](/zh/guide/integrations/app-consolidation) 统一来自多个桌面应用程序的 MCP 服务器配置： @@ -100,7 +101,7 @@ head: --- -## 🖥️ [Claude Desktop 集成](/guide/integrations/claude-desktop) +## 🖥️ [Claude Desktop 集成](/zh/guide/integrations/claude-desktop) 通过两种灵活方法与 Claude Desktop 无缝集成： @@ -112,7 +113,7 @@ head: --- -## ⚙️ [服务器管理](/guide/essentials/server-management) +## ⚙️ [服务器管理](/zh/guide/essentials/server-management) 全面的 MCP 服务器生命周期和配置管理： @@ -125,7 +126,7 @@ head: --- -## 🏷️ [服务器过滤](/guide/advanced/server-filtering) +## 🏷️ [服务器过滤](/zh/guide/advanced/server-filtering) 使用灵活的基于标签的过滤控制对特定 MCP 服务器的访问： @@ -138,7 +139,20 @@ head: --- -## ⚡ [快速启动](/guide/advanced/fast-startup) +## 🤖 [AI 助手内部工具](/zh/reference/internal-tools) + +为 AI 助手提供程序化 MCP 服务器管理功能： + +- **🔍 发现工具（5 个）** - 搜索注册表、检查可用性、获取服务器信息 +- **⚙️ 安装工具（3 个）** - 安装、更新、卸载服务器，支持依赖解析 +- **🔧 管理工具（6 个）** - 启用/禁用服务器、监控健康、编辑配置 +- **🛡️ 安全功能** - 内置验证、备份、回滚和错误恢复 + +适用场景：AI 助手自动化、程序化服务器管理、DevOps 工作流、智能监控 + +--- + +## ⚡ [快速启动](/zh/guide/advanced/fast-startup) 通过异步服务器加载让 1MCP 立即运行： @@ -170,6 +184,7 @@ head: | **Claude Desktop** | ✅ 必不可少 | 🔧 集成 | 🔧 设置 | 📊 远程 | 🛡️ 安全 | | **服务器管理** | 🚫 隐藏 | ✅ 必不可少 | ✅ 关键 | ✅ 关键 | ✅ 高级 | | **服务器过滤** | 🚫 透明 | 🔧 可配置 | 🛡️ 访问控制 | 🛡️ 策略 | 🛡️ 多租户 | +| **内部工具** | 🚫 隐藏 | 🤖 自动化 | 🔧 管理 | ⚡ 关键 | 🔧 企业 | **图例**：✅ 主要好处 | ⚡ 性能 | 🔒 安全 | 🔧 技术 | 🛡️ 保护 | 📊 监控 | 🚫 不相关 @@ -179,22 +194,23 @@ head: ### 快速入门路径 -1. **[5 分钟]** 基本 MCP 聚合 → [快速开始](/guide/getting-started) -2. **[15 分钟]** 添加身份验证 → [安全功能](/guide/advanced/security) -3. **[30 分钟]** 生产功能 → [企业功能](/guide/advanced/enterprise) +1. **[5 分钟]** 基本 MCP 聚合 → [快速开始](/zh/guide/getting-started) +2. **[15 分钟]** 添加身份验证 → [安全功能](/zh/guide/advanced/security) +3. **[30 分钟]** 生产功能 → [企业功能](/zh/guide/advanced/enterprise) ### 特定功能指南 -- **安全设置** → [身份验证指南](/guide/advanced/authentication) -- **配置** → [配置指南](/guide/essentials/configuration) -- **开发** → [开发者功能](/guide/integrations/developer-tools) -- **应用集成** → [应用整合指南](/guide/integrations/app-consolidation) -- **Claude Desktop** → [Claude Desktop 集成](/guide/integrations/claude-desktop) -- **服务器管理** → [服务器管理指南](/guide/essentials/server-management) -- **服务器过滤** → [服务器过滤指南](/guide/advanced/server-filtering) -- **性能** → [快速启动指南](/guide/advanced/fast-startup) -- **架构** → [系统架构](/reference/architecture) +- **安全设置** → [身份验证指南](/zh/guide/advanced/authentication) +- **配置** → [配置指南](/zh/guide/essentials/configuration) +- **开发** → [开发者功能](/zh/guide/integrations/developer-tools) +- **应用集成** → [应用整合指南](/zh/guide/integrations/app-consolidation) +- **Claude Desktop** → [Claude Desktop 集成](/zh/guide/integrations/claude-desktop) +- **服务器管理** → [服务器管理指南](/zh/guide/essentials/server-management) +- **服务器过滤** → [服务器过滤指南](/zh/guide/advanced/server-filtering) +- **AI 自动化** → [内部工具参考](/zh/reference/internal-tools) +- **性能** → [快速启动指南](/zh/guide/advanced/fast-startup) +- **架构** → [系统架构](/zh/reference/architecture) --- -> **💡 专业提示**：从[核心功能](/guide/essentials/core-features)开始，然后随着需求增长添加高级功能。每个功能都设计为独立工作，可以增量启用。 +> **💡 专业提示**：从[核心功能](/zh/guide/essentials/core-features)开始，然后随着需求增长添加高级功能。每个功能都设计为独立工作，可以增量启用。 diff --git a/docs/zh/reference/internal-tools.md b/docs/zh/reference/internal-tools.md new file mode 100644 index 00000000..68a6fd17 --- /dev/null +++ b/docs/zh/reference/internal-tools.md @@ -0,0 +1,262 @@ +--- +title: MCP 内部工具参考 +description: 1MCP 内部工具的完整参考文档 - 用于服务器发现、安装和管理的 MCP 协议工具 +head: + - ['meta', { name: 'keywords', content: 'MCP 内部工具,协议工具,AI 助手,服务器管理,自动化' }] + - ['meta', { property: 'og:title', content: 'MCP 内部工具参考 - 1MCP' }] + - ['meta', { property: 'og:description', content: '1MCP 内部工具的完整参考文档，用于 AI 助手的程序化服务器管理' }] +--- + +# MCP 内部工具 + +MCP 内部工具是通过 Model Context Protocol 暴露给 AI 助手的工具，使其能够以编程方式发现、安装、管理和与 MCP 服务器交互。这些工具通过 MCP 协议提供，为服务器生命周期管理提供全面的自动化能力。 + +与供人类使用的 CLI 命令不同，内部工具专为 AI 助手集成和自动化工作流设计。 + +## 概述 + +内部工具按功能领域分为三类： + +- **[发现工具](./internal-tools/discovery)** - 搜索注册表并发现 MCP 服务器 +- **[安装工具](./internal-tools/installation)** - 安装、更新和移除 MCP 服务器 +- **[管理工具](./internal-tools/management)** - 控制服务器操作状态和配置 + +## 工具类别 + +### 发现工具 + +使 AI 助手能够从各种注册表和来源搜索和发现 MCP 服务器。 + +- **`mcp_search`** - 在 MCP 注册表中搜索服务器 +- **`mcp_registry_status`** - 检查注册表可用性和健康状况 +- **`mcp_registry_info`** - 获取详细的注册表信息 +- **`mcp_registry_list`** - 列出可用的注册表 +- **`mcp_info`** - 获取详细的服务器信息 + +### 安装工具 + +提供完整的 MCP 服务器生命周期管理： + +- **`mcp_install`** - 从注册表或自定义源安装 MCP 服务器 +- **`mcp_uninstall`** - 移除 MCP 服务器，支持备份和回滚 +- **`mcp_update`** - 将 MCP 服务器更新到最新版本或指定版本 + +### 管理工具 + +提供对 MCP 服务器的操作控制： + +- **`mcp_enable`** - 启用已禁用的 MCP 服务器 +- **`mcp_disable`** - 禁用 MCP 服务器而不移除 +- **`mcp_list`** - 列出 MCP 服务器，支持过滤和状态信息 +- **`mcp_status`** - 获取详细的服务器状态和健康信息 +- **`mcp_reload`** - 重新加载服务器配置或重启服务器 +- **`mcp_edit`** - 编辑 MCP 服务器配置 + +## 示例用法 + +### AI 助手工作流程 + +以下是 AI 助手如何使用这些内部工具来帮助用户： + +#### 示例 1：设置开发环境 + +```json +// 用户："我需要使用 PostgreSQL 数据库和 Git 仓库" + +[ + { + "tool": "mcp_search", + "arguments": { + "query": "postgresql database" + } + }, + { + "tool": "mcp_search", + "arguments": { + "query": "git repository" + } + }, + { + "tool": "mcp_install", + "arguments": { + "serverName": "postgres", + "version": "2.0.1" + } + }, + { + "tool": "mcp_install", + "arguments": { + "serverName": "git", + "version": "3.1.0" + } + }, + { + "tool": "mcp_list", + "arguments": { + "filter": "enabled" + } + } +] +``` + +#### 示例 2：服务器健康监控 + +```json +// AI 助手执行例行健康检查 + +[ + { + "tool": "mcp_list", + "arguments": {} + }, + { + "tool": "mcp_status", + "arguments": { + "serverName": "filesystem" + } + }, + { + "tool": "mcp_registry_status", + "arguments": {} + } +] +``` + +### 程序化集成 + +#### 示例 3：CI/CD 流水线集成 + +```bash +# 使用 1MCP 内部工具通过 API 的部署脚本 +#!/bin/bash + +# 为项目安装所需的 MCP 服务器 +echo "正在安装 MCP 服务器..." + +curl -X POST http://localhost:3050/mcp \ + -H "Content-Type: application/json" \ + -d '{ + "tool": "mcp_install", + "arguments": { + "serverName": "project-dependencies", + "version": "latest" + } + }' + +# 验证安装 +curl -X POST http://localhost:3050/mcp \ + -H "Content-Type: application/json" \ + -d '{ + "tool": "mcp_list", + "arguments": { + "filter": "enabled" + } + }' +``` + +#### 示例 4：基础设施即代码 + +```json +{ + "mcp_servers": [ + { + "tool": "mcp_install", + "arguments": { + "serverName": "redis-cache", + "version": "1.2.1", + "config": { + "host": "localhost", + "port": 6379 + } + } + }, + { + "tool": "mcp_install", + "arguments": { + "serverName": "file-storage", + "version": "2.0.0", + "config": { + "rootPath": "/data/storage" + } + } + } + ] +} +``` + +## 使用场景 + +### AI 助手自动化 + +AI 助手可以使用这些工具自动： + +- **发现相关服务器** 用于特定任务或领域 +- **安装所需服务器** 基于用户需求或项目要求 +- **管理服务器生命周期** 包括更新、健康监控和故障排除 +- **编排复杂工作流** 涉及多个 MCP 服务器 + +### 程序化服务器管理 + +开发者可以将这些工具集成到： + +- **CI/CD 流水线** 用于自动 MCP 服务器部署 +- **基础设施即代码** 解决方案用于服务器配置 +- **监控系统** 用于服务器健康和性能跟踪 +- **自动化测试** 框架用于 MCP 服务器验证 + +### 动态配置 + +工具支持动态服务器管理场景： + +- **按需安装服务器** 基于用户需求 +- **优雅服务器更新** 支持回滚能力 +- **基于健康的故障转移** 和恢复 +- **环境间的配置同步** + +## 关键特性 + +### 全面的 API 覆盖 + +所有内部工具提供完整的输入/输出架构： + +- **类型化参数** 带有验证和约束 +- **结构化输出** 保持一致的数据格式 +- **错误处理** 提供详细的错误信息 +- **进度反馈** 用于长时间运行的操作 + +### 安全操作 + +内部工具优先考虑安全性和可靠性： + +- **备份和恢复** 支持破坏性操作 +- **依赖验证** 防止破坏性更改 +- **回滚支持** 用于失败的操作 +- **操作前后健康检查** + +### 集成友好 + +专为 AI 助手集成设计： + +- **语义化命名** 遵循 MCP 约定 +- **描述性错误消息** 用于故障排除 +- **进度指示器** 提供用户反馈 +- **交叉引用** 相关操作 + +## API 参考 + +详细的 API 文档包括架构、参数和示例： + +- **[发现工具](./internal-tools/discovery)** - 发现域工具和工作流 +- **[安装工具](./internal-tools/installation)** - 安装域工具和安全功能 +- **[管理工具](./internal-tools/management)** - 管理域工具和操作控制 + +## 入门指南 + +AI 助手通常在连接到 1MCP 实例时通过 MCP 协议访问这些工具。工具根据服务器的能力和配置自动可用。 + +对于 CLI 用户，许多这些功能也可通过 [1MCP 命令](../commands/) 获得，提供用户友好的相同操作界面。 + +## 另请参阅 + +- [服务器管理指南](../guide/essentials/server-management) - 手动服务器管理 +- [MCP 命令参考](../commands/mcp/) - CLI 服务器管理命令 diff --git a/docs/zh/reference/internal-tools/discovery.md b/docs/zh/reference/internal-tools/discovery.md new file mode 100644 index 00000000..7a2a4af1 --- /dev/null +++ b/docs/zh/reference/internal-tools/discovery.md @@ -0,0 +1,103 @@ +--- +title: 发现工具 +description: MCP 内部工具，用于发现和搜索 MCP 服务器、注册表和服务器信息 +head: + - ['meta', { name: 'keywords', content: 'MCP 发现,服务器搜索,注册表,AI 助手' }] + - ['meta', { property: 'og:title', content: '发现工具 - 1MCP 内部工具' }] + - ['meta', { property: 'og:description', content: 'MCP 内部工具，用于服务器发现和注册表管理' }] +--- + +# 发现工具 + +发现工具使 AI 助手能够从各种来源查找、评估和收集 MCP 服务器的信息。这些工具提供全面的搜索功能、注册表管理和详细的服务器信息检索。 + +## 工具概述 + +### mcp_search + +在 MCP 注册表中搜索符合特定条件的服务器。支持高级过滤、分类和模糊匹配，为任何用例找到相关服务器。 + +### mcp_registry_status + +检查 MCP 注册表的可用性和健康状况。提供性能指标、正常运行时间信息和连接状态，确保可靠的注册表访问。 + +### mcp_registry_info + +获取特定 MCP 注册表的详细信息，包括支持的功能、身份验证要求和服务器统计信息。 + +### mcp_registry_list + +列出所有可用的 MCP 注册表及其功能和访问要求。帮助识别不同类型服务器的最佳注册表来源。 + +### mcp_info + +检索特定 MCP 服务器的全面信息，包括功能、要求、版本历史记录和兼容性详细信息。 + +## 使用模式 + +### 服务器发现工作流 + +AI 助手通常遵循此发现模式： + +1. **注册表检查**：使用 `mcp_registry_status` 验证注册表可用性 +2. **服务器搜索**：使用 `mcp_search` 配合相关过滤器和分类 +3. **服务器详细信息**：使用 `mcp_info` 获取有希望的服务器的详细信息 +4. **注册表信息**：使用 `mcp_registry_info` 和 `mcp_registry_list` 了解可用来源 + +### 搜索策略 + +AI 助手可以通过以下方式有效搜索服务器： + +- 使用带有相关关键词和分类的特定查询 +- 应用标签、功能和兼容性过滤器 +- 利用模糊匹配进行近似搜索 +- 按相关性、受欢迎程度或时间排序结果 + +### 注册表管理 + +AI 助手通过以下方式管理注册表操作： + +- 检查多个注册表状态以确保可靠性 +- 比较不同注册表中的服务器可用性 +- 监控注册表性能和响应时间 +- 识别最适合特定需求的注册表 + +## AI 助手使用场景 + +### 自动服务器发现 + +AI 助手可以通过分析用户需求、使用适当参数搜索、根据需求评估服务器功能以及推荐最佳服务器选择来自动查找合适的服务器。 + +### 注册表健康监控 + +AI 助手可以监控注册表可用性、随时间跟踪性能指标、识别连接问题以及报告需要注意的注册表问题。 + +### 服务器评估 + +AI 助手可以通过比较功能、检查版本兼容性、分析依赖要求以及评估社区指标（如受欢迎程度和评分）来评估服务器。 + +## 工具交互 + +发现工具可以有效结合使用： + +- **发现过程**：`mcp_registry_status` → `mcp_search` → `mcp_info` +- **注册表分析**：`mcp_registry_list` → `mcp_registry_info` → `mcp_registry_status` +- **服务器研究**：`mcp_search`（带过滤器）→ `mcp_info`（获取详细信息） +- **健康监控**：定期 `mcp_registry_status` 检查以确保可靠性 + +## AI 助手最佳实践 + +1. **在执行搜索前检查注册表状态** +2. **使用带有相关过滤器的特定搜索词** +3. **使用不同注册表比较多个来源** +4. **在推荐前验证服务器兼容性** +5. **监控搜索性能** 并调整查询复杂度 +6. **在适当时缓存服务器信息** 以提高效率 +7. **在主要来源不可用时使用备用注册表** +8. **验证搜索结果** 的相关性和准确性 + +## 另请参阅 + +- [安装工具](./installation) - 服务器生命周期管理 +- [管理工具](./management) - 服务器运营控制 +- [MCP 命令参考](../../commands/mcp/) - CLI 发现命令 diff --git a/docs/zh/reference/internal-tools/index.md b/docs/zh/reference/internal-tools/index.md new file mode 100644 index 00000000..e0406eab --- /dev/null +++ b/docs/zh/reference/internal-tools/index.md @@ -0,0 +1,280 @@ +--- +title: 内部工具概述 +description: 1MCP 内部工具介绍，用于 AI 助手自动化和服务器管理 +head: + - ['meta', { name: 'keywords', content: 'MCP 内部工具,AI 助手,自动化,服务器管理' }] + - ['meta', { property: 'og:title', content: '内部工具概述 - 1MCP' }] + - ['meta', { property: 'og:description', content: '1MCP 内部工具介绍，用于 AI 助手自动化和服务器管理' }] +--- + +# 内部工具概述 + +内部工具是通过 MCP 协议暴露给 AI 助手的工具，使其能够以编程方式管理 1MCP 生态系统中的 MCP 服务器。这些工具提供全面的服务器发现、安装和运营管理自动化能力。 + +## 目的与设计 + +内部工具专门为 **AI 助手集成**而设计，而非人工交互。虽然 CLI 命令提供用户友好的服务器管理界面，但内部工具提供程序化访问，具有： + +- **结构化输入/输出** 遵循 MCP 协议标准 +- **全面架构** 具有验证和类型安全 +- **原子操作** 支持回滚和错误处理 +- **自动化友好** 的工作流和状态管理 + +## 启用内部工具 + +内部工具默认禁用，必须通过 CLI 标志或环境变量明确启用。这确保只有预期的 AI 助手可以访问这些强大的管理功能。 + +### CLI 标志 + +启动 1MCP 服务器时启用内部工具： + +```bash +# 启用所有内部工具 +npx -y @1mcp/agent serve --enable-internal-tools + +# 按名称启用特定工具 +npx -y @1mcp/agent serve --internal-tools="search,list,status,registry" + +# 按类别启用工具 +npx -y @1mcp/agent serve --internal-tools="discovery,management" + +# 仅启用安全（只读）工具 +npx -y @1mcp/agent serve --internal-tools="safe" +``` + +### 可用工具类别 + +- **discovery**：注册表搜索和服务器发现工具 +- **installation**：服务器安装、更新和移除工具 +- **management**：服务器控制和配置工具 +- **safe**：只读工具（发现 + 只读管理） + +### 单个工具 + +- **search**：`mcp_search` - 在 MCP 注册表中搜索服务器 +- **list**：`mcp_list` - 列出带有状态的 MCP 服务器 +- **status**：`mcp_status` - 获取详细的服务器状态 +- **registry**：注册表管理工具 +- **install/uninstall/update**：安装工具 +- **enable/disable/edit**：管理工具 + +### 安全注意事项 + +启用内部工具时： + +- **最小权限原则**：仅启用您用例所需的工具 +- **网络安全**：确保 1MCP 仅可受信任的 AI 助手访问 +- **使用安全模式**：在可能的情况下考虑使用 `--internal-tools="safe"` 进行只读操作 +- **监控使用情况**：定期审查 AI 助手正在使用哪些工具 + +### 示例 + +```bash +# 开发环境 - 完全访问 +npx -y @1mcp/agent serve --enable-internal-tools + +# 生产环境 - 仅发现和管理 +npx -y @1mcp/agent serve --internal-tools="discovery,management" + +# 只读监控设置 +npx -y @1mcp/agent serve --internal-tools="safe" + +# 特定服务器管理场景 +npx -y @1mcp/agent serve --internal-tools="search,list,status,enable,disable" +``` + +## 工具架构 + +内部工具系统被组织为三个逻辑领域，镜像服务器生命周期： + +```mermaid +graph TD + A[发现工具] --> B[安装工具] + B --> C[管理工具] + + A1[mcp_search] --> A + A2[mcp_registry_status] --> A + A3[mcp_registry_info] --> A + A4[mcp_registry_list] --> A + A5[mcp_info] --> A + + B1[mcp_install] --> B + B2[mcp_uninstall] --> B + B3[mcp_update] --> B + + C1[mcp_enable] --> C + C2[mcp_disable] --> C + C3[mcp_list] --> C + C4[mcp_status] --> C + C5[mcp_reload] --> C + C6[mcp_edit] --> C +``` + +## 工作流模式 + +### 典型的 AI 助手工作流 + +AI 助手通常在使用内部工具时遵循以下模式： + +1. **发现阶段** + - 使用 `mcp_registry_status` 检查注册表可用性 + - 使用 `mcp_search` 查找相关服务器 + - 使用 `mcp_info` 获取详细的服务器信息 + +2. **安装阶段** + - 使用 `mcp_install` 安装所需的服务器 + - 使用 `mcp_status` 验证安装成功 + - 使用 `mcp_list` 确认服务器可用性 + +3. **管理阶段** + - 使用 `mcp_enable`/`mcp_disable` 控制服务器状态 + - 使用 `mcp_status` 进行持续健康监控 + - 使用 `mcp_reload`/`mcp_edit` 进行配置更改 + +### 自动化工作流示例 + +```javascript +// AI 助手为开发环境设置的示例工作流 + +async function setupDevelopmentEnvironment() { + // 1. 发现可用服务器 + const registryStatus = await mcp_registry_status(); + if (!registryStatus.isAvailable) { + throw new Error('注册表不可用'); + } + + // 2. 搜索开发工具 + const devTools = await mcp_search({ + query: '开发调试工具', + category: 'development', + }); + + // 3. 安装所需服务器 + const installations = []; + for (const server of devTools.results) { + const installResult = await mcp_install({ + name: server.name, + version: server.recommendedVersion, + }); + installations.push(installResult); + } + + // 4. 验证安装 + const serverList = await mcp_list(); + const installedServers = serverList.servers.filter((server) => server.status === 'running'); + + // 5. 根据需要启用服务器 + for (const server of installedServers) { + if (server.disabled) { + await mcp_enable({ name: server.name }); + } + } + + return { + installed: installations.length, + running: installedServers.length, + servers: installedServers, + }; +} +``` + +## 关键能力 + +### 安全操作 + +所有内部工具优先考虑操作安全性： + +- **事务支持** 支持回滚能力 +- **依赖验证** 防止破坏性更改 +- **健康检查** 操作前后验证 +- **备份创建** 用于破坏性操作 +- **原子提交** 配置适当的清理 + +### 丰富反馈 + +工具提供全面的操作反馈： + +- **进度指示器** 用于长时间运行的操作 +- **详细状态信息** 包括日志和指标 +- **错误上下文** 提供建议的解决方案 +- **操作历史** 用于审计和调试 + +### 集成特性 + +专为 AI 助手集成设计： + +- **语义化命名** 遵循 MCP 约定 +- **一致的架构** 跨所有工具 +- **跨工具兼容性** 共享数据结构 +- **可扩展设计** 支持未来工具添加 + +## 工具领域 + +### 发现工具 + +专注于发现和评估 MCP 服务器： + +- **注册表集成** 支持多个注册表源 +- **高级搜索** 支持过滤和分类 +- **服务器信息** 包含功能和需求 +- **健康监控** 用于注册表服务 + +### 安装工具 + +处理完整的服务器生命周期管理： + +- **灵活安装** 支持多种来源（注册表、git、自定义） +- **版本管理** 支持依赖解析 +- **安全卸载** 支持备份和回滚 +- **更新自动化** 支持兼容性检查 + +### 管理工具 + +提供运营控制和监控： + +- **状态管理** 支持优雅的状态转换 +- **配置编辑** 支持验证和热重载 +- **健康监控** 提供详细诊断 +- **性能跟踪** 支持指标和警报 + +## 与 CLI 命令的比较 + +| 方面 | 内部工具 | CLI 命令 | +| -------------- | ------------- | --------------- | +| **目标用户** | AI 助手 | 人类 | +| **接口** | MCP 协议 | 命令行 | +| **输出格式** | 结构化数据 | 人类可读文本 | +| **错误处理** | 结构化异常 | 用户友好的消息 | +| **自动化** | 原生支持 | 需要手动脚本 | +| **批处理操作** | 内置功能 | 需要 shell 脚本 | +| **集成** | 直接 MCP 访问 | 外部进程执行 | + +## 最佳实践 + +### 对于 AI 助手开发者 + +- **使用结构化错误处理** 和适当的异常处理 +- **实现重试逻辑** 处理临时故障 +- **缓存服务器信息** 减少注册表调用 +- **验证先决条件** 在操作之前 +- **监控操作进度** 并提供用户反馈 + +### 对于工具用户 + +- **规划操作** 在执行前了解依赖关系 +- **使用状态检查** 验证操作成功 +- **实施备份策略** 用于关键服务器 +- **定期监控服务器** 状况 +- **记录自定义配置** 确保可重现性 + +## 下一步 + +- **[发现工具](./discovery)** - 了解服务器发现能力 +- **[安装工具](./installation)** - 了解安装和生命周期管理 +- **[管理工具](./management)** - 探索操作控制功能 +- **[主要参考页面](../internal-tools.md)** - 完整参考文档 + +## 另请参阅 + +- [MCP 协议规范](https://modelcontextprotocol.io/) - 了解底层协议 +- [CLI 命令参考](../../commands/) - 人类友好的服务器管理替代方案 diff --git a/docs/zh/reference/internal-tools/installation.md b/docs/zh/reference/internal-tools/installation.md new file mode 100644 index 00000000..dba5408f --- /dev/null +++ b/docs/zh/reference/internal-tools/installation.md @@ -0,0 +1,106 @@ +--- +title: 安装工具 +description: MCP 内部工具，用于安装、更新和管理 MCP 服务器的完整生命周期 +head: + - ['meta', { name: 'keywords', content: 'MCP 安装,服务器管理,生命周期,AI 助手' }] + - ['meta', { property: 'og:title', content: '安装工具 - 1MCP 内部工具' }] + - ['meta', { property: 'og:description', content: 'MCP 内部工具，用于服务器安装和生命周期管理' }] +--- + +# 安装工具 + +安装工具使 AI 助手能够管理 MCP 服务器的完整生命周期，从初始安装到更新和移除。这些工具提供灵活的安装选项、依赖管理和安全操作处理。 + +## 工具概述 + +### mcp_install + +从各种来源安装 MCP 服务器，包括注册表、Git 仓库或自定义 URL。支持版本指定、依赖解析和自动配置。 + +### mcp_uninstall + +安全地移除 MCP 服务器，具有依赖检查、备份选项和相关资源清理。确保在不影响其他服务器的情况下干净移除。 + +### mcp_update + +将 MCP 服务器更新到更新版本，具有兼容性检查、回滚功能和迁移支持。自动处理版本冲突和依赖更新。 + +## 使用模式 + +### 服务器安装工作流 + +AI 助手通常遵循此安装模式： + +1. **发现**：使用发现工具找到合适的服务器 +2. **安装**：使用 `mcp_install` 配合适当的源和版本 +3. **验证**：使用管理工具确认安装成功 +4. **配置**：应用必要的设置并启用服务器 + +### 安装来源 + +AI 助手可以从多个来源安装服务器： + +- **注册表安装**：从官方或第三方注册表安装 +- **Git 仓库**：直接从 Git 仓库安装 +- **自定义来源**：从特定 URL 或本地路径安装 +- **版本指定**：安装特定版本或最新的稳定版本 + +### 更新管理 + +AI 助手通过以下方式处理更新： + +- **兼容性检查**：在更新前验证版本兼容性 +- **依赖解析**：自动处理依赖更新 +- **回滚支持**：如果出现问题则恢复到以前版本 +- **迁移协助**：帮助配置迁移 + +## AI 助手使用场景 + +### 自动环境设置 + +AI 助手可以通过识别特定任务所需的服务器、安装正确版本的服务器、自动解析依赖以及配置服务器以立即使用来自动设置完整环境。 + +### 维护和更新 + +AI 助手可以通过监控可用更新、在维护窗口期间安排更新、在应用更新前测试兼容性以及如果出现问题则处理回滚来维护服务器环境。 + +### 服务器管理 + +AI 助手可以通过跟踪已安装的服务器和版本、识别未使用或已弃用的服务器、协调服务器组的更新以及确保跨部署的一致环境来管理服务器群体。 + +## 工具交互 + +安装工具与其他工具类别有效协作： + +- **发现到安装**：发现工具 → `mcp_install` → 管理工具验证 +- **更新工作流**：管理工具状态检查 → `mcp_update` → `mcp_reload` +- **移除过程**：管理工具依赖检查 → `mcp_uninstall` → 清理 +- **完整生命周期**：发现 → 安装 → 管理 → 更新 → 移除 + +## AI 助手最佳实践 + +1. **在安装尝试前验证先决条件** +2. **根据系统要求使用兼容版本** +3. **检查依赖** 以避免冲突 +4. **在主要更新前创建备份** +5. **首先在安全环境中测试安装** +6. **监控安装进度** 并适当处理错误 +7. **记录自定义配置** 以确保可重现性 +8. **在应用更新前规划回滚策略** + +## 安全注意事项 + +AI 助手应通过以下方式优先考虑安全性： + +- 在安装前检查系统兼容性 +- 验证来源真实性和安全性 +- 使用适当的版本约束 +- 在可能的情况下在非生产环境中测试 +- 维护关键配置的备份副本 +- 遵循依赖最佳实践以避免冲突 + +## 另请参阅 + +- [发现工具](./discovery) - 服务器发现和搜索 +- [管理工具](./management) - 服务器运营控制 +- [MCP 命令参考](../../commands/mcp/) - CLI 安装命令 diff --git a/docs/zh/reference/internal-tools/management.md b/docs/zh/reference/internal-tools/management.md new file mode 100644 index 00000000..57279ea4 --- /dev/null +++ b/docs/zh/reference/internal-tools/management.md @@ -0,0 +1,107 @@ +--- +title: 管理工具 +description: MCP 内部工具，用于运营控制、状态监控和 MCP 服务器配置管理 +head: + - ['meta', { name: 'keywords', content: 'MCP 管理,服务器控制,状态监控,配置管理' }] + - ['meta', { property: 'og:title', content: '管理工具 - 1MCP 内部工具' }] + - ['meta', { property: 'og:description', content: 'MCP 内部工具，用于服务器运营控制和监控' }] +--- + +# 管理工具 + +管理工具提供对 MCP 服务器的全面运营控制，包括状态管理、配置编辑、健康监控和性能优化。这些工具专注于为 AI 助手提供细粒度的控制权和实时可见性。 + +## 工具概述 + +### mcp_enable + +启用已禁用的 MCP 服务器，支持选择性功能激活和依赖验证。确保服务器在启用前满足所有运行要求。 + +### mcp_disable + +优雅地禁用 MCP 服务器，支持连接排空和状态保存。可选择临时禁用或完全停止服务。 + +### mcp_list + +列出所有配置的 MCP 服务器，支持按状态、标签和功能进行过滤。提供详细的运行时信息和配置概览。 + +### mcp_status + +获取特定服务器的详细状态信息，包括健康指标、性能统计和诊断信息。支持历史状态跟踪和趋势分析。 + +### mcp_reload + +重新加载服务器配置或重启服务器，支持热重载和零停机更新。包含回滚机制和配置验证。 + +### mcp_edit + +编辑 MCP 服务器配置，提供实时验证、模式检查和语法高亮。支持配置模板和批量更新。 + +## 使用模式 + +### 服务器生命周期管理 + +AI 助手通过简单的工具调用管理服务器状态： + +- 使用 `mcp_enable` 激活已禁用的服务器并进行验证 +- 使用 `mcp_disable` 优雅地关闭服务器并进行连接排空 +- 使用 `mcp_status` 在操作前后验证服务器状态 +- 使用 `mcp_list` 发现服务器并按状态或标签过滤 + +### 配置管理 + +AI 助手通过以下方式管理配置： + +- 使用 `mcp_edit` 进行配置更改并进行验证 +- 使用 `mcp_reload` 应用配置更新 +- 使用 `mcp_edit` 内置的备份和回滚功能 +- 支持零停机更新的热重载功能 + +### 健康监控 + +AI 助手通过以下方式监控服务器健康： + +- 使用带有指标和诊断选项的 `mcp_status` +- 通过 `mcp_list` 后跟状态检查监控多个服务器 +- 分析性能趋势和资源使用情况 +- 识别并响应健康问题 + +## AI 助手使用场景 + +### 服务器健康监控 + +AI 助手可以通过定期检查所有服务器的状态、识别不健康或不活动的服务器、并报告需要注意的问题来维护服务器健康。 + +### 配置管理 + +AI 助手可以通过对服务器组应用标准配置、在应用前验证更改、以及使用备份功能进行安全修改来自动化配置任务。 + +### 故障排除 + +AI 助手可以通过收集状态和诊断信息、分析高资源使用率或错误率等常见问题、并提供可行的建议来诊断服务器问题。 + +## 工具交互 + +管理工具可以有效地按顺序工作： + +- **状态管理**：`mcp_list` → `mcp_status` → `mcp_enable/disable` +- **配置更新**：`mcp_status` → `mcp_edit` → `mcp_reload` +- **健康监控**：带有指标的 `mcp_status` 用于持续监控 +- **定向操作**：带过滤的 `mcp_list` 用于特定服务器组 + +## AI 助手最佳实践 + +1. **在更改前验证先决条件** +2. **使用状态检查** 确认操作成功 +3. **优雅地处理错误** 并提供清晰反馈 +4. **在操作前后监控服务器健康** +5. **使用 mcp_edit 选项创建备份** +6. **高效使用批量操作** 进行多服务器管理 +7. **实现重试逻辑** 处理临时故障 +8. **在应用更改前验证配置** + +## 另请参阅 + +- [发现工具](./discovery) - 服务器发现和评估 +- [安装工具](./installation) - 服务器生命周期管理 +- [MCP 命令参考](../../commands/mcp/) - CLI 服务器管理命令