Skip to content

Commit c3a775c

Browse files
jhlibertyjhliberty
committed
Initial commit: PolyNeural.ai MCPB Bundle
- Add MCPB bundle with stdio MCP server implementation - Include HTTP bridge to PolyNeural.ai backend MCP endpoints - Support for 16+ knowledge graph operations - Backward compatible with Claude Desktop (dxt_version) - Future compatible with MCPB standard (manifest_version) - Comprehensive documentation and installation guide - Security validated - no hardcoded secrets or sensitive data - Ready for public release
0 parents  commit c3a775c

File tree

11 files changed

+2795
-0
lines changed

11 files changed

+2795
-0
lines changed

‎.gitignore‎

Lines changed: 64 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,64 @@
1+
# Dependencies
2+
node_modules/
3+
npm-debug.log*
4+
yarn-debug.log*
5+
yarn-error.log*
6+
7+
# Environment variables (never commit these!)
8+
.env
9+
.env.local
10+
.env.development.local
11+
.env.test.local
12+
.env.production.local
13+
14+
# IDE files
15+
.vscode/
16+
.idea/
17+
*.swp
18+
*.swo
19+
*~
20+
21+
# OS generated files
22+
.DS_Store
23+
.DS_Store?
24+
._*
25+
.Spotlight-V100
26+
.Trashes
27+
ehthumbs.db
28+
Thumbs.db
29+
30+
# Logs
31+
logs/
32+
*.log
33+
34+
# Runtime data
35+
pids/
36+
*.pid
37+
*.seed
38+
*.pid.lock
39+
40+
# Coverage directory used by tools like istanbul
41+
coverage/
42+
43+
# Dependency directories
44+
jspm_packages/
45+
46+
# Optional npm cache directory
47+
.npm
48+
49+
# Optional REPL history
50+
.node_repl_history
51+
52+
# Output of 'npm pack'
53+
*.tgz
54+
55+
# Yarn Integrity file
56+
.yarn-integrity
57+
58+
# Build outputs (if any)
59+
dist/
60+
build/
61+
62+
# Temporary files
63+
tmp/
64+
temp/

‎INSTALL.md‎

Lines changed: 99 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,99 @@
1+
# Installation Guide for @polyneural/mcpb
2+
3+
## Current Compatibility Status (September 2025)
4+
5+
🚫 **Claude Desktop** (Current): Uses legacy DXT format (requires `dxt_version` field)
6+
✅ **Future MCPB Apps**: Will use MCPB standard (requires `manifest_version` field)
7+
8+
**Our Solution**: The bundle includes both fields for maximum compatibility!
9+
10+
## Installation Options
11+
12+
### Option 1: Claude Desktop (Current)
13+
14+
1. **Download**: Get `polyneural-mcpb.mcpb` from releases
15+
2. **Install**: Double-click the `.mcpb` file
16+
3. **Configure**: Set your PolyNeural.ai API key when prompted
17+
4. **Use**: Access 16 knowledge graph tools in Claude
18+
19+
### Option 2: Manual Installation (All Apps)
20+
21+
1. **Clone/Download** this repository
22+
2. **Install dependencies**: `npm install`
23+
3. **Configure** your MCP client with:
24+
```json
25+
{
26+
"mcpServers": {
27+
"@polyneural/mcpb": {
28+
"command": "node",
29+
"args": ["/path/to/mcpb/server/index.js"],
30+
"env": {
31+
"API_URL": "https://api.polyneural.ai",
32+
"API_KEY": "kg_your_api_key_here",
33+
"DEBUG": "false",
34+
"TIMEOUT": "30"
35+
}
36+
}
37+
}
38+
}
39+
```
40+
41+
## Configuration
42+
43+
### Required Settings
44+
- **API_KEY**: Your PolyNeural.ai API key (format: `kg_xxxxxxxx`)
45+
46+
### Optional Settings
47+
- **API_URL**: API endpoint (default: `https://api.polyneural.ai`)
48+
- **DEBUG**: Enable debug logging (default: `false`)
49+
- **TIMEOUT**: Request timeout in seconds (default: `30`)
50+
51+
## Troubleshooting
52+
53+
### "Extension Preview Failed" (Claude Desktop)
54+
This usually means:
55+
1. **Missing API Key**: Ensure your PolyNeural.ai API key is set
56+
2. **Invalid Format**: API key must start with `kg_`
57+
3. **Network Issues**: Check connection to `api.polyneural.ai`
58+
59+
### "No tools available"
60+
1. **Restart** your MCP client after installation
61+
2. **Check logs** for authentication errors
62+
3. **Verify** the PolyNeural.ai backend is accessible
63+
64+
### Debug Mode
65+
Enable debug logging to see detailed communication:
66+
```bash
67+
DEBUG=true npm start
68+
```
69+
70+
## Available Tools
71+
72+
Once installed, you'll have access to 16 knowledge graph tools:
73+
74+
### Core Operations
75+
- `create_entities` - Store new knowledge entities
76+
- `create_relations` - Create relationships between entities
77+
- `search_nodes` - Search the knowledge graph
78+
- `open_nodes` - Retrieve specific entities
79+
- `read_graph` - Get complete graph structure
80+
81+
### Advanced Operations
82+
- `add_observations` - Add details to existing entities
83+
- `delete_entities` - Remove entities
84+
- `delete_relations` - Remove relationships
85+
- `get_entities_by_identifiers` - Bulk entity retrieval
86+
- `get_entity_relationships` - Get entity connections
87+
- `get_recent_changes` - Recent activity tracking
88+
- `get_trending_entities` - Popular entities
89+
- `search_with_frecency` - Smart search with ranking
90+
91+
## Support
92+
93+
- **Issues**: [GitHub Issues](https://github.com/PolyNeural-ai/mcpb/issues)
94+
- **Documentation**: [docs.polyneural.ai](https://docs.polyneural.ai)
95+
- **Email**: [email protected]
96+
97+
---
98+
99+
**Note**: This bundle is designed to work with both current Claude Desktop (DXT format) and future MCPB-compliant applications. As MCPB support rolls out, the experience will only get better!

‎MIGRATION.md‎

Lines changed: 127 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,127 @@
1+
# DXT to MCPB Migration Summary
2+
3+
## Overview
4+
5+
Successfully migrated the PolyNeural.ai Desktop Extension from DXT format to MCPB (MCP Bundle) format, following the official [MCPB specification](https://github.com/anthropics/mcpb).
6+
7+
## Changes Made
8+
9+
### 1. Manifest Updates
10+
- ✅ Added `manifest_version: "0.1"` (MCPB specification)
11+
- ✅ Kept `dxt_version: "0.1"` (backward compatibility for current Claude Desktop)
12+
- ✅ Updated name: `polyneural-ai-dxt` → `@polyneural/mcpb`
13+
- ✅ Updated display name to reflect MCP Bundle
14+
- ✅ Updated repository URLs from `/dxt` to `/mcpb`
15+
- ✅ Updated support URLs accordingly
16+
- ✅ Removed icon reference (no icon file exists)
17+
18+
### 2. Package.json Updates
19+
- ✅ Updated package name to `@polyneural/mcpb`
20+
- ✅ Updated description to mention MCP Bundle
21+
- ✅ Updated repository URL to point to mcpb repo
22+
- ✅ Added `mcpb` keyword
23+
- ✅ Updated script descriptions
24+
25+
### 3. Server Implementation Improvements
26+
- ✅ Updated debug messages from "DXT" to "MCPB"
27+
- ✅ Updated server name to `@polyneural/mcpb`
28+
- ✅ Enhanced error handling with timeout management
29+
- ✅ Added proper AbortController for request timeouts
30+
- ✅ Improved error messages with specific network issues
31+
- ✅ Added User-Agent header for API requests
32+
33+
### 4. Documentation Updates
34+
- ✅ Updated README.md with MCPB-focused content
35+
- ✅ Added MCPB installation instructions
36+
- ✅ Updated troubleshooting section for bundle context
37+
- ✅ Added MCPB compliance section
38+
- ✅ Updated architecture diagrams
39+
40+
### 5. Tooling & Validation
41+
- ✅ Created `validate-mcpb.js` script for bundle validation
42+
- ✅ Created `create-bundle.sh` for automated bundle creation
43+
- ✅ Added npm scripts: `validate` and `bundle`
44+
- ✅ Comprehensive validation of manifest structure
45+
46+
## MCPB Compliance Checklist
47+
48+
- ✅ **Valid manifest.json** with `manifest_version: "0.1"`
49+
- ✅ **Proper MCP server** implementation using `@modelcontextprotocol/sdk`
50+
- ✅ **User configuration** via `user_config` field with proper types
51+
- ✅ **Platform compatibility** declarations (darwin, win32, linux)
52+
- ✅ **Error handling** and timeout management
53+
- ✅ **Tool declarations** - 16 comprehensive tools declared
54+
- ✅ **Standard directory structure** with server/index.js entry point
55+
- ✅ **Production dependencies** bundled properly
56+
57+
## Bundle Structure
58+
59+
```
60+
@polyneural/mcpb/
61+
├── manifest.json # MCPB manifest with user_config
62+
├── package.json # npm package definition
63+
├── README.md # Updated documentation
64+
├── server/
65+
│ └── index.js # MCP server entry point
66+
├── node_modules/ # Bundled dependencies
67+
├── validate-mcpb.js # Bundle validation script
68+
└── create-bundle.sh # Bundle creation script
69+
```
70+
71+
## User Configuration
72+
73+
The bundle supports these user-configurable options:
74+
- **api_url**: PolyNeural.ai API endpoint (default: https://api.polyneural.ai)
75+
- **api_key**: API key for authentication (sensitive, required)
76+
- **debug_mode**: Enable debug logging (boolean, default: false)
77+
- **timeout**: Request timeout in seconds (number, 5-120, default: 30)
78+
79+
## Testing & Validation
80+
81+
```bash
82+
# Validate bundle structure
83+
npm run validate
84+
85+
# Create production bundle
86+
npm run bundle
87+
88+
# Test server (requires API key)
89+
API_KEY=kg_test_key npm start
90+
```
91+
92+
## Distribution
93+
94+
The bundle can be distributed as:
95+
1. **MCPB file**: `polyneural-mcpb.mcpb` (ZIP archive)
96+
2. **npm package**: `@polyneural/mcpb`
97+
3. **Git repository**: Direct clone and manual installation
98+
99+
## Architecture Unchanged
100+
101+
The core HTTP bridge architecture remains the same:
102+
- MCP Client (stdio) ↔ MCPB Server ↔ PolyNeural.ai HTTP API
103+
- All business logic stays in the backend
104+
- Clean separation of concerns maintained
105+
106+
## Compatibility Discovery
107+
108+
🚫 **Interesting Discovery**: While updating to MCPB specification, we discovered that Claude Desktop (as of September 2025) hasn't been updated to support their own MCPB standard yet! It still requires the old `dxt_version` field instead of the new `manifest_version`.
109+
110+
**Solution**: The bundle uses DXT format for current Claude Desktop compatibility:
111+
- `dxt_version: "0.1"` - Works with current Claude Desktop
112+
- Future MCPB versions will be created when Claude Desktop supports the new format
113+
114+
## Next Steps
115+
116+
1. Test the bundle with Claude Desktop (current version with DXT support)
117+
2. Monitor Claude Desktop updates for full MCPB support
118+
3. Publish to npm registry as `@polyneural/mcpb`
119+
4. Create GitHub releases with `.mcpb` files
120+
5. Update documentation on polyneural.ai website
121+
6. Notify existing DXT users about the migration
122+
123+
---
124+
125+
**Migration completed successfully!** 🎉
126+
127+
The bundle is now fully MCPB-compliant and ready for distribution in the MCP Bundle ecosystem.

0 commit comments

Comments
 (0)