{"id":29019492,"url":"https://github.com/railsware/coupler-io-mcp-server","last_synced_at":"2025-06-26T00:30:43.663Z","repository":{"id":295661384,"uuid":"966662495","full_name":"railsware/coupler-io-mcp-server","owner":"railsware","description":"Coupler.io MCP server","archived":false,"fork":false,"pushed_at":"2025-06-12T11:48:48.000Z","size":446,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":8,"default_branch":"main","last_synced_at":"2025-06-12T12:44:49.206Z","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/railsware.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}},"created_at":"2025-04-15T09:07:22.000Z","updated_at":"2025-06-12T11:48:53.000Z","dependencies_parsed_at":"2025-06-12T12:33:07.176Z","dependency_job_id":"c447285a-3dd0-4dc1-9d55-4df86a6137ca","html_url":"https://github.com/railsware/coupler-io-mcp-server","commit_stats":null,"previous_names":["railsware/coupler-io-mcp-server"],"tags_count":2,"template":false,"template_full_name":null,"purl":"pkg:github/railsware/coupler-io-mcp-server","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/railsware%2Fcoupler-io-mcp-server","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/railsware%2Fcoupler-io-mcp-server/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/railsware%2Fcoupler-io-mcp-server/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/railsware%2Fcoupler-io-mcp-server/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/railsware","download_url":"https://codeload.github.com/railsware/coupler-io-mcp-server/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/railsware%2Fcoupler-io-mcp-server/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":261976614,"owners_count":23239163,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","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":"2025-06-26T00:30:41.964Z","updated_at":"2025-06-26T00:30:43.532Z","avatar_url":"https://github.com/railsware.png","language":"TypeScript","funding_links":[],"categories":["🌐 Web Development"],"sub_categories":[],"readme":"[![Lint \u0026 Test](https://github.com/railsware/coupler-io-mcp-server/actions/workflows/lint-and-test.yml/badge.svg)](https://github.com/railsware/coupler-io-mcp-server/actions/workflows/lint-and-test.yml)\n\n# Coupler.io official MCP server\nThe Coupler.io MCP Server is a Model Context Protocol (MCP) server that provides seamless integration with Coupler.io APIs.\n\n**⚠️ Alpha Software Warning**  \nThis repo contains early alpha software under active development. Features are incomplete and subject to breaking changes.\n\n## Use Cases\n- Extracting and analyzing data from Coupler.io data flows.\n\n## Prerequisites\n1. Install [Docker](https://www.docker.com/) to run the server in a container.\n2. Make sure Docker is running.\n3. Get a [Coupler.io Personal Access Token](https://app.coupler.io/app/ai_features)\n\n## Running the server\n### Claude Desktop\n```json\n{\n  \"mcpServers\": {\n    \"coupler\": {\n      \"command\": \"docker\",\n      \"args\": [\n        \"run\",\n        \"--pull=always\",\n        \"-e\",\n        \"COUPLER_ACCESS_TOKEN\",\n        \"--rm\",\n        \"-i\",\n        \"ghcr.io/railsware/coupler-io-mcp-server\"\n      ],\n      \"env\": {\n        \"COUPLER_ACCESS_TOKEN\": \"\u003cyour_token\u003e\"\n      }\n    }\n  }\n}\n```\n\nNOTE: `\"--pull=always\"` will ensure you always have the latest image by pulling it from the registry.\nRemove this line, if you're offline or if you specifically want to use the image you've already pulled previously.\n\n## Tools\n### Data flows\n- **get-data** - Gets the result of a data flow run as a SQLite file and executes a read-only query on it. Currently, only data flows built from a dashboard or dataset template are supported.\n  - `dataflowId`: Data flow ID (`string`, **required**)\n  - `executionId`: Data flow run ID (`string`, **required**)\n  - `query`: Query to run on the data flow SQLite file (`string`, **required**)\n\n- **get-schema** - Gets the data flow schema file. Currently, only data flows built from a dashboard or dataset template are supported.\n  - `dataflowId`: Data flow ID (`string`, **required**)\n  - `executionId`: Data flow run ID (`string`, **required**)\n\n## Development\n\nInstall NodeJS:\n```shell\nasdf plugin add nodejs https://github.com/asdf-vm/asdf-nodejs.git\nasdf install\n```\n\nInstall dependencies:\n```shell\nnpm install\n```\n\nInstall Git hooks:\n```shell\nlefthook install\n```\n\nSet environment variables:\n```shell\ncp .env.example .env.local\n```\n\n### Work with a raw server\nRun the MCP server:\n```shell\nnpm run dev\n```\n\n#### Run [MCP server inspector](https://github.com/modelcontextprotocol/inspector) for debugging\nCaveat: make sure to keep only a single inspector tab open at all times, until [this inspector bug](https://github.com/modelcontextprotocol/inspector/issues/302) is fixed.\n```shell\n# Run this and follow the instructions to view the inspector\nnpm run inspect:node\n```\n\n#### Tail logs\nOur local MCP server uses STDIO transport, therefore logs must go to a file. This may come in handy when debugging.\n```shell\ntail -f log/development.log | npx pino-pretty\n```\nYou can also optionally capture STDIO messages in the log file by setting `LOG_STDIO=1` when running the server.\nIf you're debugging a containerized server, you'd likely want to mount a dir at `/app/log` to be able to access the logs it generates.\n\n### Working with development Docker image\nBuild Docker image for development:\n```shell\nbin/build_image\n```\n\nYou can now run the container with the MCP inspector for debugging in UI mode:\n```shell\nnpm run inspect:docker\n```\n\nOr run the container within Claude Desktop, configured with your `.env.local` file in the project.\nGrab the absolute path to your env file `realpath .env.local`.\nNavigate to Settings \u003e Developer \u003e Edit Config.\nEdit your `claude_desktop_config.json`, add an entry for our server:\n```json\n{\n  \"mcpServers\": {\n    \"coupler-io-mcp-server-development\": {\n      \"command\": \"docker\",\n      \"args\": [\n        \"run\",\n        \"--env-file\",\n        \"/path/to/your/.env.local\",\n        \"--add-host\",\n        \"storage.test=host-gateway\",\n        \"--add-host\",\n        \"lvh.me=host-gateway\",\n        \"--rm\",\n        \"-i\",\n        \"coupler-io-mcp-server-development\"\n      ]\n    }\n  }\n}\n```\n\n### Using MCP inspector\n[Use MCP inspector in CLI mode](https://github.com/modelcontextprotocol/inspector/blob/24e8861a88f843d57cdb637a5ae3afd0e528c5f3/README.md#cli-mode) for smoke testing the server with a short feedback loop:\n\n```shell\n# List tools\nnpx @modelcontextprotocol/inspector --cli npm run dev --method tools/list\n\n# Call list-dataflows tool\nnpx @modelcontextprotocol/inspector --cli npm run dev --method tools/call --tool-name list-dataflows\n\n# Call get-schema tool\nnpx @modelcontextprotocol/inspector --cli npm run dev --method tools/call --tool-name get-schema --tool-arg dataflowId=\u003cyour data flow ID\u003e\n```\n\n### Testing the Docker image against Coupler.io staging\nWe build and publish a Docker image with of our MCP server, tagged `edge`, on every push to the `main` branch.\n\nConfigure Claude Desktop to run the Docker container against Coupler.io staging.\nNavigate to Settings \u003e Developer \u003e Edit Config.\nEdit your `claude_desktop_config.json`, add an entry for the staging server:\n```json\n{\n  \"mcpServers\": {\n    \"coupler-io-mcp-server-staging\": {\n      \"command\": \"docker\",\n      \"args\": [\n        \"run\",\n        \"-e\",\n        \"COUPLER_ACCESS_TOKEN\",\n        \"--env\",\n        \"COUPLER_API_HOST=https://app.couplerstaging.dev/mcp\",\n        \"--rm\",\n        \"-i\",\n        \"ghcr.io/railsware/coupler-io-mcp-server:edge\"\n      ],\n      \"env\": {\n        \"COUPLER_ACCESS_TOKEN\": \"\u003cyour_coupler_access_token_from_staging\u003e\"\n      }\n    }\n  }\n}\n```\n\n[Optional] Enable logging for debugging by adding the following args:\n```json\n        \"--env\",\n        \"LOG_LEVEL=debug\",\n        \"--env\",\n        \"LOG_STDIO=1\",\n```\n\n### Building and pushing a release image\nThe development cycle looks like this:\n- open a PR with changes\n- use the `pr-N`-tagged image to debug and test your changes\n- merge the PR to `main`\n- test the `edge` image\n- build and push a release image tagged as `latest`\n\nTo build and push a release image:\n- draft a [new release](https://github.com/railsware/coupler-io-mcp-server/releases/new?target=main)\n- specify a new tag to be created on publish. Use [semver](https://semver.org/)\n- Target: `main` branch\n- Generate or write release notes\n- click \"Publish release\"\n- check [the docker image workflow](https://github.com/railsware/coupler-io-mcp-server/actions/workflows/publish-docker-image.yml) progress\n\nYou should now be able to smoke-test the release image.\n```shell\n# Pull the `latest` image\ndocker pull ghcr.io/railsware/coupler-io-mcp-server\n```\nRun the release image with Claude Desktop and other supported clients.\n\n## License\nThis project is licensed under the terms of the MIT open source license. Please refer to [MIT](./LICENSE) for the full terms.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frailsware%2Fcoupler-io-mcp-server","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Frailsware%2Fcoupler-io-mcp-server","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frailsware%2Fcoupler-io-mcp-server/lists"}