{"id":38585702,"url":"https://github.com/flier/mcp-zookeeper","last_synced_at":"2026-01-17T08:19:22.343Z","repository":{"id":315567967,"uuid":"1059980991","full_name":"flier/mcp-zookeeper","owner":"flier","description":null,"archived":false,"fork":false,"pushed_at":"2025-09-19T09:34:39.000Z","size":86,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"dev","last_synced_at":"2025-09-19T11:38:48.103Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/flier.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-09-19T08:09:22.000Z","updated_at":"2025-09-19T09:34:43.000Z","dependencies_parsed_at":"2025-09-19T11:38:51.788Z","dependency_job_id":"d4489f08-1c20-4253-b8e4-6343d2227396","html_url":"https://github.com/flier/mcp-zookeeper","commit_stats":null,"previous_names":["flier/mcp-zookeeper"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/flier/mcp-zookeeper","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/flier%2Fmcp-zookeeper","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/flier%2Fmcp-zookeeper/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/flier%2Fmcp-zookeeper/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/flier%2Fmcp-zookeeper/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/flier","download_url":"https://codeload.github.com/flier/mcp-zookeeper/tar.gz/refs/heads/dev","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/flier%2Fmcp-zookeeper/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28504362,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-17T06:57:29.758Z","status":"ssl_error","status_checked_at":"2026-01-17T06:56:03.931Z","response_time":85,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-01-17T08:19:20.643Z","updated_at":"2026-01-17T08:19:22.329Z","avatar_url":"https://github.com/flier.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# MCP ZooKeeper Server\n\nA Model Context Protocol (MCP) server that provides tools for interacting with Apache ZooKeeper. This server allows you to read, write, and manage ZooKeeper nodes and directories through a standardized MCP interface.\n\n## Features\n\n### Node Operations\n- **Read Text Nodes**: Read node contents as text with optional line filtering (head/tail)\n- **Read Binary Nodes**: Read binary node contents with MIME type detection\n- **Write Nodes**: Create new nodes or overwrite existing node content\n- **Edit Nodes**: Apply diff operations to text nodes with preview mode support\n- **Remove Nodes**: Delete nodes with support for recursive deletion of child nodes\n- **Get Node Statistics**: Retrieve detailed metadata information about nodes\n\n### Directory Operations\n- **Simple Directory Listing**: Simple directory listing with `[NODE]`/`[DIR]` prefixes\n- **Detailed Directory Listing**: Detailed directory listing with file sizes and sorting options\n- **Recursive Directory Tree**: Display recursive directory tree as JSON structure\n- **Create Directory**: Create directories and all necessary parent directories\n\n### Advanced Features\n- **Human-readable file sizes**: Automatic formatting (B, KB, MB, GB, TB)\n- **Flexible sorting**: Sort directory contents by name or size\n- **Error handling**: Comprehensive error messages and graceful failure handling\n- **Type safety**: Full TypeScript support with Zod schema validation\n- **Resource support**: Support for ZooKeeper nodes as MCP resources\n\n## Installation\n\n```bash\nnpm install -g mcp-zookeeper\n```\n\n## Usage\n\n### Starting the Server\n\n#### Standard Input/Output Mode (Recommended for MCP clients)\n```bash\nmcp-server-zookeeper\n```\n\n#### HTTP Server Mode\n```bash\nmcp-server-zookeeper --host 0.0.0.0 --port 3000\n```\n\n#### Command Line Options\n```bash\nmcp-server-zookeeper [options]\n\nOptions:\n  -h, --help              Show help information\n  -H, --host=HOST         Host to listen on (default: 127.0.0.1)\n  -p, --port=PORT         Port to listen on\n  -s, --zkServers=SERVERS ZooKeeper servers address (default: localhost:2181)\n```\n\n### Configuration\n\nThe server connects to ZooKeeper using the following default settings:\n- **Host**: localhost:2181\n- **Session Timeout**: 30 seconds\n- **Retry Attempts**: 3\n- **Connection Delay**: 100 milliseconds\n\nYou can customize these settings using environment variables:\n- `ZK_SERVERS`: ZooKeeper connection string (default: \"localhost:2181\")\n- `ZK_SESSION_TIMEOUT`: Session timeout in milliseconds (default: 30000)\n- `ZK_RETRIES`: Number of retry attempts (default: 3)\n- `ZK_SPIN_DELAY`: Delay between connection attempts in milliseconds (default: 100)\n\n## Available Tools\n\n### `read_text_node`\nRead the complete contents of a node as text.\n\n**Parameters:**\n- `path` (string): The path to the node to read\n- `head` (number, optional): Return only the first N lines\n- `tail` (number, optional): Return only the last N lines\n\n**Example:**\n```json\n{\n  \"path\": \"/config/app.properties\",\n  \"head\": 10\n}\n```\n\n### `read_binary_node`\nRead a binary node and return base64-encoded data with MIME type.\n\n**Parameters:**\n- `path` (string): The path to the binary node to read\n\n**Example:**\n```json\n{\n  \"path\": \"/data/image.png\"\n}\n```\n\n### `write_node`\nCreate a new node or overwrite an existing node with new content.\n\n**Parameters:**\n- `path` (string): The path to the node to write\n- `content` (string): The content to write\n- `encoding` (string, optional): Text encoding (default: \"utf-8\")\n\n**Example:**\n```json\n{\n  \"path\": \"/config/settings.json\",\n  \"content\": \"{\\\"debug\\\": true, \\\"port\\\": 8080}\",\n  \"encoding\": \"utf-8\"\n}\n```\n\n### `edit_node`\nApply diff operations to a text node.\n\n**Parameters:**\n- `path` (string): The path to the node to edit\n- `diffs` (array): List of diff operations\n- `dryRun` (boolean): Preview changes without applying them (default: false)\n\n**Example:**\n```json\n{\n  \"path\": \"/config/app.properties\",\n  \"diffs\": [\n    {\"op\": 1, \"text\": \"debug=true\\n\"},\n    {\"op\": -1, \"text\": \"debug=false\\n\"}\n  ],\n  \"dryRun\": true\n}\n```\n\n### `remove_node`\nRemove a node. Supports recursive deletion of child nodes.\n\n**Parameters:**\n- `path` (string): The path to the node to remove\n- `version` (number, optional): The version of the node to remove\n- `recursive` (boolean): Whether to recursively remove the node and all its children (default: false)\n\n**Example:**\n```json\n{\n  \"path\": \"/temp/data\",\n  \"recursive\": true\n}\n```\n\n### `create_directory`\nCreate a directory and all necessary parent directories.\n\n**Parameters:**\n- `path` (string): The path to the directory to create\n\n**Example:**\n```json\n{\n  \"path\": \"/data/logs/2024/01\"\n}\n```\n\n### `list_directory`\nGet a simple listing of directory contents.\n\n**Parameters:**\n- `path` (string): The path to the directory to list\n\n**Example Output:**\n```text\n[NODE] file1.txt\n[DIR] subdirectory\n[NODE] file2.txt\n```\n\n### `list_directory_with_sizes`\nGet a detailed listing with file sizes and sorting options.\n\n**Parameters:**\n- `path` (string): The path to the directory to list\n- `sortBy` (string, optional): Sort by \"name\" or \"size\" (default: \"name\")\n\n**Example Output:**\n```text\n[DIR] subdirectory\n[FILE] file1.txt                       100 B\n[FILE] file2.txt                       2.00 MB\n\nTotal: 2 files, 1 directories\nCombined size: 2.00 MB\n```\n\n### `list_directory_tree`\nGet a recursive tree view of directories as a JSON structure.\n\n**Parameters:**\n- `path` (string): The root directory path to list\n\n**Example Output:**\n```json\n{\n  \"name\": \"root\",\n  \"type\": \"directory\",\n  \"children\": [\n    {\n      \"name\": \"file1.txt\",\n      \"type\": \"file\"\n    },\n    {\n      \"name\": \"subdir\",\n      \"type\": \"directory\",\n      \"children\": [\n        {\n          \"name\": \"file2.txt\",\n          \"type\": \"file\"\n        }\n      ]\n    }\n  ]\n}\n```\n\n### `get_node_stat`\nRetrieve detailed metadata information about a node or directory.\n\n**Parameters:**\n- `path` (string): The path to the node to get statistics for\n\n**Example Output:**\n```json\n{\n  \"czxid\": 1234567890,\n  \"mzxid\": 1234567890,\n  \"ctime\": 1640995200000,\n  \"mtime\": 1640995200000,\n  \"version\": 1,\n  \"cversion\": 0,\n  \"aversion\": 0,\n  \"ephemeralOwner\": 0,\n  \"dataLength\": 1024,\n  \"numChildren\": 3,\n  \"pzxid\": 1234567890\n}\n```\n\n## Resource Support\n\nThis server supports ZooKeeper nodes as MCP resources, allowing clients to access node content through resource URIs:\n\n- **Resource URI Format**: `zk:///{node}`\n- **Auto-completion**: Supports node path auto-completion\n- **Content Reading**: Direct node content access through resource interface\n\n## Development\n\n### Prerequisites\n- Node.js 18+\n- pnpm\n- TypeScript\n- ZooKeeper server (for testing)\n\n### Setup\n```bash\ngit clone https://github.com/flier/mcp-zookeeper.git\ncd mcp-zookeeper\npnpm install\n```\n\n### Building\n```bash\npnpm build\n```\n\n### Testing\n```bash\n# Run all tests\npnpm test\n\n# Run tests with coverage report\npnpm test:coverage\n\n# Run tests in watch mode\npnpm test:watch\n\n# Start test UI\npnpm test:ui\n```\n\n### Linting\n```bash\npnpm lint\n```\n\n### Development Server\n```bash\n# Start development server (watch mode)\npnpm watch\n\n# Start MCP inspector\npnpm inspector\n```\n\n## Troubleshooting\n\n### Common Issues\n\n#### Connection Problems\n**Issue**: Unable to connect to ZooKeeper server\n**Solutions**:\n1. Check if ZooKeeper server is running\n2. Verify the connection string is correct\n3. Check network connectivity and firewall settings\n4. Ensure ZooKeeper server port (default 2181) is accessible\n\n#### Permission Issues\n**Issue**: Permission denied errors when accessing nodes\n**Solutions**:\n1. Check ZooKeeper ACL configuration\n2. Ensure client has appropriate permissions\n3. Verify node path is correct\n\n#### Session Timeout\n**Issue**: Session timeout causing operation failures\n**Solutions**:\n1. Increase session timeout duration\n2. Check network stability\n3. Reduce retry interval\n\n### Debug Mode\n\nEnable verbose logging:\n```bash\nDEBUG=mcp-zookeeper:* mcp-server-zookeeper\n```\n\n### Health Check\n\nUse MCP inspector to verify server status:\n```bash\npnpm inspector\n```\n\n## API Reference\n\n### Utility Functions\n\n#### `formatSize(bytes: number): string`\nFormats a byte count into a human-readable string.\n\n**Parameters:**\n- `bytes`: The number of bytes to format\n\n**Returns:**\n- A formatted string with the size and unit (e.g., \"1.50 KB\", \"2.00 MB\")\n\n**Examples:**\n```typescript\nformatSize(0)        // \"0 B\"\nformatSize(1024)     // \"1.00 KB\"\nformatSize(1536)     // \"1.50 KB\"\nformatSize(1048576)  // \"1.00 MB\"\nformatSize(-100)     // \"0 B\"\n```\n\n## Error Handling\n\nThe server provides comprehensive error handling with descriptive error messages:\n\n- **Node not found**: Clear indication when a node doesn't exist\n- **Permission denied**: Authentication and authorization errors\n- **Connection issues**: ZooKeeper connectivity problems\n- **Invalid parameters**: Schema validation errors\n- **Session timeout**: Session expiration errors\n- **Version conflict**: Node version mismatch errors\n\n## License\n\nMIT License - see [LICENSE](LICENSE) file for details.\n\n## Contributing\n\nWe welcome community contributions! Please follow these steps:\n\n1. Fork the repository\n2. Create a feature branch (`git checkout -b feature/amazing-feature`)\n3. Commit your changes (`git commit -m 'Add some amazing feature'`)\n4. Push to the branch (`git push origin feature/amazing-feature`)\n5. Open a Pull Request\n\n### Development Guidelines\n\n- Ensure all tests pass\n- Add tests for new functionality\n- Follow existing code style\n- Update relevant documentation\n\n## Additional Documentation\n\n- **[Usage Examples](EXAMPLES.md)**: Detailed usage examples and best practices\n- **[Changelog](CHANGELOG.md)**: Version update records\n- **[API Reference](README.md#api-reference)**: Complete API documentation\n- **[Troubleshooting](README.md#troubleshooting)**: Common issue solutions\n\n## Support\n\n- **Issues**: [GitHub Issues](https://github.com/flier/mcp-zookeeper/issues)\n- **Documentation**: [GitHub Wiki](https://github.com/flier/mcp-zookeeper/wiki)\n- **Email**: flier.lu@gmail.com\n\n## Changelog\n\n### v1.0.0\n- Initial version release\n- Support for basic ZooKeeper node operations\n- MCP tools and resource interface\n- Full TypeScript support\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fflier%2Fmcp-zookeeper","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fflier%2Fmcp-zookeeper","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fflier%2Fmcp-zookeeper/lists"}