# Publishing FlashLeads MCP Server to npm
## Step 1: Prepare for Publishing
1. **Update repository URLs in package.json** (replace with your actual GitHub repo):
```json
"repository": {
"type": "git",
"url": "https://github.com/YOUR_USERNAME/flashleads-mcp-server.git"
}
```
2. **Build the package**:
```bash
cd mcp-server
npm run build
```
3. **Test locally** (optional but recommended):
```bash
npm link
flashleads-mcp
# Press Ctrl+C to stop
npm unlink -g @flashleads/mcp-server
```
## Step 2: Publish to npm
1. **Login to npm** (create account at https://www.npmjs.com if you don't have one):
```bash
npm login
```
2. **Publish the package**:
```bash
npm publish --access public
```
3. **Verify it's published**:
- Visit: https://www.npmjs.com/package/@flashleads/mcp-server
- Check version, readme, etc.
## Step 3: Users Can Now Use It!
### For End Users:
**Configure Claude Desktop** - Edit `~/Library/Application Support/Claude/claude_desktop_config.json`:
```json
{
"mcpServers": {
"flashleads": {
"command": "npx",
"args": [
"-y",
"@flashleads/mcp-server"
],
"env": {
"FLASHLEADS_API_KEY": "their-secret-key-here",
"FLASHLEADS_API_URL": "https://api.flashleads.io"
}
}
}
}
```
That's it! No installation needed - `npx` downloads and runs it automatically.
## Step 4: User Gets API Key
Users need to get an API key first by calling your backend:
```bash
curl -X POST https://api.flashleads.io/api/provision/create-api-key \
-H "Content-Type: application/json" \
-d '{
"secretKey": "my-secure-password-123",
"workspaceName": "My AI Workspace",
"email": "user@example.com"
}'
```
Response:
```json
{
"success": true,
"apiKey": "my-secure-password-123",
"workspaceId": "clx...",
"workspaceName": "My AI Workspace",
"credits": 1000,
"message": "Workspace and API key created successfully"
}
```
## Step 5: User Uses Claude
1. Restart Claude Desktop completely
2. Look for 🔌 icon - should show "flashleads" connected
3. Start chatting:
- "Find me 10 coffee shop leads in Seattle"
- "Get restaurant contacts in Miami"
- etc.
---
## Updating the Package
When you make changes:
1. **Update version in package.json**:
```json
"version": "1.0.1"
```
2. **Build and publish**:
```bash
npm run build
npm publish
```
3. **Users automatically get updates** - npx always fetches the latest version (or they can specify version)
---
## Version Management
Users can specify exact versions:
```json
{
"command": "npx",
"args": [
"-y",
"@flashleads/mcp-server@1.0.0"
]
}
```
Or use version ranges:
- `@flashleads/mcp-server@^1.0.0` - any 1.x.x
- `@flashleads/mcp-server@latest` - always latest
---
## Production Checklist
Before publishing, ensure:
- [x] `bdr-node` backend is deployed to production
- [x] Production API URL is ready (e.g., https://api.flashleads.io)
- [ ] Update `FLASHLEADS_API_URL` default in code or docs
- [ ] Test the entire flow end-to-end
- [ ] Add rate limiting/monitoring
- [ ] Set up error tracking (Sentry, etc.)
- [ ] Create landing page explaining the MCP server
- [ ] Write user documentation
---
## Optional: GitHub Setup
Create a separate repo for the MCP server:
```bash
cd mcp-server
git init
git add .
git commit -m "Initial commit"
git branch -M main
git remote add origin https://github.com/YOUR_USERNAME/flashleads-mcp-server.git
git push -u origin main
```
Add a good README.md explaining:
- What it does
- How to get API key
- How to configure Claude Desktop
- Example usage
- Troubleshooting
---
## Example User Documentation
Share this with users:
### Quick Start
1. **Get your API key**:
```bash
curl -X POST https://api.flashleads.io/api/provision/create-api-key \
-H "Content-Type: application/json" \
-d '{"secretKey":"my-password","email":"you@email.com"}'
```
2. **Configure Claude Desktop**:
**macOS**: Edit `~/Library/Application Support/Claude/claude_desktop_config.json`
**Windows**: Edit `%APPDATA%\Claude\claude_desktop_config.json`
```json
{
"mcpServers": {
"flashleads": {
"command": "npx",
"args": ["-y", "@flashleads/mcp-server"],
"env": {
"FLASHLEADS_API_KEY": "my-password",
"FLASHLEADS_API_URL": "https://api.flashleads.io"
}
}
}
}
```
3. **Restart Claude Desktop**
4. **Start using it**:
- "Find me 20 restaurant leads in New York"
- "Get coffee shop contacts in San Francisco"
- "Search for dental offices in Chicago"
---
## Monitoring Usage
Track usage in your backend:
- Check `MCPApiKey.requestCount`
- Monitor `Workspace.credits`
- Set up alerts for high usage
- Track popular search queries
---
## Support
Users can:
- Report issues: https://github.com/YOUR_USERNAME/flashleads-mcp-server/issues
- Email: support@flashleads.io
- Docs: https://flashleads.io/docs
