{"id":51135606,"url":"https://github.com/bmlt-enabled/bmlt-mcp-server","last_synced_at":"2026-06-25T17:30:57.586Z","repository":{"id":313203390,"uuid":"1050392966","full_name":"bmlt-enabled/bmlt-mcp-server","owner":"bmlt-enabled","description":"BMLT MCP Server","archived":false,"fork":false,"pushed_at":"2025-10-20T12:56:53.000Z","size":61,"stargazers_count":0,"open_issues_count":1,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-10-20T14:49:01.225Z","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":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/bmlt-enabled.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-09-04T11:18:26.000Z","updated_at":"2025-10-20T12:55:35.000Z","dependencies_parsed_at":"2025-10-20T14:35:00.817Z","dependency_job_id":"11fdd7d5-feae-487b-8371-13ebda6ed7d7","html_url":"https://github.com/bmlt-enabled/bmlt-mcp-server","commit_stats":null,"previous_names":["bmlt-enabled/bmlt-mcp-server"],"tags_count":6,"template":false,"template_full_name":null,"purl":"pkg:github/bmlt-enabled/bmlt-mcp-server","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bmlt-enabled%2Fbmlt-mcp-server","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bmlt-enabled%2Fbmlt-mcp-server/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bmlt-enabled%2Fbmlt-mcp-server/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bmlt-enabled%2Fbmlt-mcp-server/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/bmlt-enabled","download_url":"https://codeload.github.com/bmlt-enabled/bmlt-mcp-server/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bmlt-enabled%2Fbmlt-mcp-server/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34786225,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-25T02:00:05.521Z","response_time":101,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-06-25T17:30:57.519Z","updated_at":"2026-06-25T17:30:57.574Z","avatar_url":"https://github.com/bmlt-enabled.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# BMLT MCP Server\n\n[![npm version](https://badge.fury.io/js/bmlt-mcp-server.svg)](https://badge.fury.io/js/bmlt-mcp-server)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n[![Node.js](https://img.shields.io/badge/Node.js-18.0%2B-green.svg)](https://nodejs.org/)\n[![npm](https://img.shields.io/npm/v/bmlt-mcp-server.svg)](https://www.npmjs.com/package/bmlt-mcp-server)\n\nA Model Context Protocol (MCP) server that provides comprehensive access to BMLT (Basic Meeting List Tool) APIs for Narcotics Anonymous meetings data. Features intelligent geocoding, rate limiting, and caching for optimal performance.\n\n## 🚀 Overview\n\nThis MCP server exposes all BMLT Semantic API endpoints as tools, allowing AI assistants like Claude to query meeting data, formats, service bodies, changes, and more from any BMLT root server. Perfect for recovery-focused applications and AI assistants.\n\n## ✨ Features\n\n- **🎯 Complete API Coverage**: All 9 BMLT Semantic API endpoints\n- **🌍 Intelligent Geocoding**: Automatic address-to-coordinates conversion using OpenStreetMap\n- **⚡ Rate Limiting**: Respectful API usage with automatic rate limiting (1 req/sec for geocoding)\n- **🏠 Smart Caching**: 24-hour in-memory cache for geocoding results (up to 100 entries)\n- **🔄 Retry Logic**: Exponential backoff for rate limiting and network errors\n- **📊 Multiple Formats**: JSON, JSONP, CSV, and TSML formats\n- **🔒 Type Safety**: Full TypeScript implementation with comprehensive types\n- **🛡️ Error Handling**: Robust error handling with meaningful error messages\n- **✅ Validation**: Parameter validation and endpoint compatibility checking\n- **⚙️ Flexible Configuration**: Environment variable configuration\n\n## Available Tools\n\n### 1. `bmlt_search_meetings`\nSearch for meetings with extensive filtering options.\n\n**Parameters:**\n- `format`: Response format (`json`, `jsonp`, `tsml`)\n- `meeting_ids`: Specific meeting IDs to include/exclude\n- `weekdays`: Days of week (1=Sunday, 2=Monday, ..., 7=Saturday)\n- `venue_types`: Venue types (1=In-person, 2=Virtual, 3=Hybrid)\n- `formats`: Format IDs to include/exclude\n- `services`: Service body IDs to include/exclude\n- `recursive`: Include child service bodies\n- `SearchString`: Text to search for\n- `StringSearchIsAnAddress`: Treat search string as address\n- `lat_val`, `long_val`: Geographic coordinates\n- `geo_width`, `geo_width_km`: Search radius\n- `StartsAfterH`, `StartsAfterM`: Time filtering\n- `page_size`, `page_num`: Pagination\n- `advanced_published`: Published status filtering (default=published only, 0=all meetings, -1=unpublished only)\n- And many more...\n\n**Special Features:**\n- **Intelligent Address Geocoding**: When using `StringSearchIsAnAddress=1`, addresses are automatically geocoded to coordinates using OpenStreetMap's Nominatim service, avoiding BMLT server geocoding issues\n- **Rate-Limited Requests**: Automatic 1.1-second intervals between geocoding requests to respect API limits\n- **Smart Caching**: Geocoding results are cached for 24 hours to improve performance\n- **Fallback Handling**: If geocoding fails, automatically falls back to text search\n\n### 2. `bmlt_get_formats`\nRetrieve available meeting formats.\n\n**Parameters:**\n- `format`: Response format (`json`, `jsonp`)\n- `lang_enum`: Language code\n- `show_all`: Show all formats or just used ones\n- `format_ids`: Specific format IDs to filter\n- `key_strings`: Format key strings to filter by\n\n### 3. `bmlt_get_service_bodies`\nGet list of service bodies.\n\n**Parameters:**\n- `format`: Response format (`json`, `jsonp`)\n- `services`: Service body IDs to include/exclude\n- `recursive`: Include child service bodies\n- `parents`: Include parent service bodies\n\n### 4. `bmlt_get_changes`\nRetrieve meeting changes within a date range.\n\n**Parameters:**\n- `format`: Response format (`json`, `jsonp`)\n- `start_date`: Start date (YYYY-MM-DD)\n- `end_date`: End date (YYYY-MM-DD)\n- `meeting_id`: Specific meeting ID\n- `service_body_id`: Service body ID\n\n### 5. `bmlt_get_field_keys`\nGet list of available field keys.\n\n**Parameters:**\n- `format`: Response format (`json`, `jsonp`)\n\n### 6. `bmlt_get_field_values`\nGet specific field values for a given field key.\n\n**Parameters:**\n- `format`: Response format (`json`, `jsonp`)\n- `meeting_key`: Field key to get values for (required)\n- `specific_formats`: Comma-separated format IDs\n- `all_formats`: Include all formats\n\n### 7. `bmlt_get_naws_dump`\nExport meeting data in NAWS format (CSV only).\n\n**Parameters:**\n- `sb_id`: Service body ID (required)\n\n### 8. `bmlt_get_server_info`\nGet server information including version and configuration.\n\n**Parameters:**\n- `format`: Response format (`json`, `jsonp`)\n\n### 9. `bmlt_get_coverage_area`\nGet geographic coverage area information.\n\n**Parameters:**\n- `format`: Response format (`json`, `jsonp`)\n\n## 📦 Installation\n\n### Prerequisites\n\n- Node.js 18.0.0 or later\n- npm or yarn\n\n### Install from npm\n\n```bash\n# Install globally\nnpm install -g bmlt-mcp-server\n\n# Or install locally in your project\nnpm install bmlt-mcp-server\n```\n\n### Install from source\n\n```bash\ngit clone https://github.com/bmlt-enabled/bmlt-mcp-server.git\ncd bmlt-mcp-server\nnpm install\nnpm run build\nnpm install -g .\n```\n\n## Configuration\n\n### Environment Variables\n\n- `BMLT_ROOT_SERVER_URL` (required): The base URL of your BMLT root server\n- `BMLT_TIMEOUT`: Request timeout in milliseconds (default: 30000)\n- `BMLT_USER_AGENT`: Custom user agent string\n\n### Example Configuration\n\n```bash\nexport BMLT_ROOT_SERVER_URL=https://bmlt.example.org/main_server/\nexport BMLT_TIMEOUT=60000\nexport BMLT_USER_AGENT=MyApp-BMLT-MCP/1.0.0\n```\n\n## Usage\n\n### Running the Server\n\n```bash\n# Using environment variables\nBMLT_ROOT_SERVER_URL=https://bmlt.example.org/main_server/ bmlt-mcp-server\n\n# Or if installed from source\nBMLT_ROOT_SERVER_URL=https://bmlt.example.org/main_server/ node dist/index.js\n```\n\n### Using with Claude Desktop\n\nAdd this to your Claude Desktop configuration:\n\n```json\n{\n  \"mcpServers\": {\n    \"bmlt\": {\n      \"command\": \"bmlt-mcp-server\",\n      \"env\": {\n        \"BMLT_ROOT_SERVER_URL\": \"https://your-bmlt-server.org/main_server/\"\n      }\n    }\n  }\n}\n```\n\nDev Example\n\n```json\n{\n  \"mcpServers\": {\n    \"bmlt-mcp-server\": {\n      \"command\": \"node\",\n      \"args\": [\"/PATH_TO_REPO/bmlt-mcp-server/dist/index.js\"],\n      \"env\": {\n        \"BMLT_ROOT_SERVER_URL\": \"https://your-bmlt-server.org/main_server/\"\n      }\n    }\n  }\n}\n```\n\n### Using with other MCP clients\n\nThe server follows the standard MCP protocol and can be used with any MCP-compatible client.\n\n## Examples\n\n### Search for Virtual Meetings on Weekends\n\n```typescript\n// Tool call\n{\n  \"name\": \"bmlt_search_meetings\",\n  \"arguments\": {\n    \"venue_types\": [2], // Virtual only\n    \"weekdays\": [1, 7], // Sunday and Saturday\n    \"page_size\": 10\n  }\n}\n```\n\n### Get All Formats in German\n\n```typescript\n// Tool call\n{\n  \"name\": \"bmlt_get_formats\",\n  \"arguments\": {\n    \"lang_enum\": \"de\",\n    \"show_all\": 1\n  }\n}\n```\n\n### Search Near Geographic Location\n\n```typescript\n// Tool call\n{\n  \"name\": \"bmlt_search_meetings\",\n  \"arguments\": {\n    \"lat_val\": 47.6062,\n    \"long_val\": -122.3321,\n    \"geo_width_km\": 10,\n    \"sort_results_by_distance\": 1\n  }\n}\n```\n\n### Get Changes for Last Month\n\n```typescript\n// Tool call\n{\n  \"name\": \"bmlt_get_changes\",\n  \"arguments\": {\n    \"start_date\": \"2024-01-01\",\n    \"end_date\": \"2024-01-31\"\n  }\n}\n```\n\n### Export NAWS Data\n\n```typescript\n// Tool call\n{\n  \"name\": \"bmlt_get_naws_dump\",\n  \"arguments\": {\n    \"sb_id\": 123\n  }\n}\n```\n\n### Search for All Meetings (Published and Unpublished)\n\n```typescript\n// Tool call\n{\n  \"name\": \"bmlt_search_meetings\",\n  \"arguments\": {\n    \"advanced_published\": 0,\n    \"venue_types\": [2],\n    \"page_size\": 10\n  }\n}\n```\n\n## Development\n\n### Setup\n\n```bash\ngit clone \u003crepository-url\u003e\ncd bmlt-mcp-server\nnpm install\n```\n\n### Available Scripts\n\n- `npm run dev`: Run in development mode with hot reload\n- `npm run build`: Build for production\n- `npm run watch`: Build and watch for changes\n- `npm run lint`: Run ESLint\n- `npm run lint:fix`: Fix ESLint issues\n- `./build.sh`: Build script with helpful output\n\n### Project Structure\n\n```\nsrc/\n├── index.ts          # Main server implementation\n├── client.ts         # BMLT API client\n├── tools.ts          # MCP tool definitions and handlers\n└── types.ts          # TypeScript type definitions\n```\n\n## API Reference\n\n### BMLT Semantic API\n\nThis server implements all endpoints from the BMLT Semantic API:\n\n- **GetSearchResults**: Meeting search with extensive filtering\n- **GetFormats**: Available meeting formats\n- **GetServiceBodies**: Service body hierarchy\n- **GetChanges**: Meeting change history\n- **GetFieldKeys**: Available database fields\n- **GetFieldValues**: Field value enumeration\n- **GetNAWSDump**: NAWS-compatible CSV export\n- **GetServerInfo**: Server configuration and capabilities\n- **GetCoverageArea**: Geographic coverage bounds\n\n### Format Support\n\n- **JSON**: Default format for most endpoints\n- **JSONP**: JSON with callback for cross-origin requests\n- **CSV**: For NAWS export only\n- **TSML**: The Semantic Meeting List format for GetSearchResults\n\n### Error Handling\n\nThe server provides comprehensive error handling:\n\n- Parameter validation errors\n- HTTP request failures\n- API-specific errors (missing required parameters, etc.)\n- Network timeouts and connectivity issues\n\n## Contributing\n\n1. Fork the repository\n2. Create a feature branch\n3. Make your changes\n4. Add tests if applicable\n5. Run linting and ensure builds pass\n6. Submit a pull request\n\n## License\n\nMIT License - see LICENSE file for details.\n\n## Support\n\n- **Issues**: Report bugs and request features on GitHub\n- **Documentation**: BMLT API documentation at https://semantic.bmlt.app\n- **Community**: BMLT community forums and Discord\n\n## Related Projects\n\n- [BMLT Root Server](https://github.com/bmlt-enabled/bmlt-root-server)\n- [BMLT Semantic Workshop](https://semantic.bmlt.app)\n- [Model Context Protocol](https://modelcontextprotocol.io)\n\n## Changelog\n\n### v1.0.0\n- Initial release\n- Complete BMLT Semantic API coverage\n- TypeScript implementation\n- Comprehensive error handling\n- Full parameter validation\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbmlt-enabled%2Fbmlt-mcp-server","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbmlt-enabled%2Fbmlt-mcp-server","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbmlt-enabled%2Fbmlt-mcp-server/lists"}