{"id":27168485,"url":"https://github.com/strowk/synf","last_synced_at":"2025-04-09T05:34:10.418Z","repository":{"id":271087857,"uuid":"907580310","full_name":"strowk/synf","owner":"strowk","description":"Development tool for Model Context Protocol servers","archived":false,"fork":false,"pushed_at":"2025-03-30T13:21:22.000Z","size":187,"stargazers_count":10,"open_issues_count":1,"forks_count":1,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-03-30T13:34:05.834Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"Rust","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/strowk.png","metadata":{"files":{"readme":"readme.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","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}},"created_at":"2024-12-23T23:22:42.000Z","updated_at":"2025-03-30T13:21:25.000Z","dependencies_parsed_at":"2025-01-05T12:28:43.558Z","dependency_job_id":"32bb5c63-a7fe-4739-9a6d-5b10a1940e84","html_url":"https://github.com/strowk/synf","commit_stats":null,"previous_names":["strowk/synf"],"tags_count":2,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/strowk%2Fsynf","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/strowk%2Fsynf/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/strowk%2Fsynf/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/strowk%2Fsynf/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/strowk","download_url":"https://codeload.github.com/strowk/synf/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247987060,"owners_count":21028891,"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-04-09T05:34:09.880Z","updated_at":"2025-04-09T05:34:10.392Z","avatar_url":"https://github.com/strowk.png","language":"Rust","funding_links":[],"categories":["Utilities"],"sub_categories":["Development Tools"],"readme":"# synf - hot reload for MCP servers\n\n`synf` can help you developing MCP server by hot reloading it on file changes.\n\nIt proxies stdio transport between MCP client and server and hot-reloads the server by rebuilding/restarting and refreshing the states (such as sending list_changed notifications).\n\n## Usage\n\nFirstly you would need to initialize synf file using command `synf init` - run this in the folder with your project. It would automatically detect used language and ask confirmation.\n\nOnce `synf init` have created `synf.toml` file, command `synf dev` can do following:\n\n- build and run your MCP server\n- wait for the first initialization request from client and cache it\n- watch for changes you make to files configurable within `synf.toml`\n- whenever you change watched files - rebuild and restart your server\n- repeat initialization request that was sent by client the first time\n- notify MCP client to repeat request for tools, prompts and resources\n- drop initialization response from server after restart, to avoid repeating it\n- if configured: cache resource subscriptions and resend them after restart\n\nYou would need to configure the command `synf dev` to be run by client that you want to integrate with your server. Command takes path to folder with your project as first argument.\n\nHere is example for Claude Desktop:\n\n```json\n{\n    \"mcpServers\": {\n        \"synf_test\": {\n            \"command\": \"synf\",\n            \"args\": [\n                \"dev\",\n                \"C:/work/synf/examples/typescript\"\n            ]\n        }\n    }\n}\n```\n\nNote: Claude Desktop appears to have a bug at the moment, where it ignores list_changed notification that synf is sending and list of tools and their descriptions would not be hot-reloaded when using that client. I expect that they would fix it eventually.\n\n### Configuration for Windows\n\nIf you are using Windows, you might need to configure `synf.toml` to use powershell for running some commands, depending on how programming language is installed for you.\n\nFor example Node.js developers would have problems with `npm` since it might be provided as a cmd script rather than an executable. You can configure `synf.toml` to use powershell for running npm:\n\n```toml\n[build]\ncommand = \"powershell\"\nargs = [\"npm run build\"]\n```\n\n## Installation\n\n### Windows with [Scoop](https://github.com/ScoopInstaller/Scoop)\n\n```bash\nscoop install https://raw.githubusercontent.com/strowk/synf/main/scoop/synf.json\n```\n\n, or if you already have it installed with scoop:\n\n```bash\nscoop update synf\n```\n\n### With bash script\n\nIn bash shell run:\n\n```bash\ncurl -s https://raw.githubusercontent.com/strowk/synf/main/install.sh | bash\n```\n\nShould work in Linux bash, Windows Git Bash and MacOS.\nFor Windows users: you might need to start Git Bash from Administrator.\n\n#### Disabling sudo\n\nBy default the script would try to install synf to `/usr/local/bin` and would require sudo rights for that,\nbut you can disable this behavior by setting `NO_SUDO` environment variable:\n\n```bash\ncurl -s https://raw.githubusercontent.com/strowk/synf/main/install.sh | NO_SUDO=1 bash\n```\n\nSudo is disabled by default for Windows Git Bash.\n\n### Manually\n\nHead to [latest release](https://github.com/strowk/synf/releases/latest), download archive for your OS/arch, unpack it and put binary somewhere in your PATH.\n\n### From sources\n\nIf your system/architecture is not supported by the script above,\nyou can install Rust and install synf from sources:\n\n```bash\ngit clone https://github.com/strowk/synf\ncargo install --path ./synf\n```\n\n## Under the hood\n\n## Initialization\n\nWhen client connects to server, it sends initialization request that would look f.e like this:\n\n```json\n{\n  \"jsonrpc\": \"2.0\",\n  \"id\": 1,\n  \"method\": \"initialize\",\n  \"params\": {\n    \"protocolVersion\": \"2024-11-05\",\n    \"capabilities\": {},\n    \"clientInfo\": {\n      \"name\": \"ExampleClient\",\n      \"version\": \"1.0.0\"\n    }\n  }\n}\n```\n\n`synf` would cache this request and repeat it after server restart, while also dropping the response from server, since the client already received it.\n\nOn first run client also would send initialized notification looking like this:\n\n```json\n{\n  \"jsonrpc\": \"2.0\",\n  \"method\": \"notifications/initialized\"\n}\n```\n\nWhen server restarted, `synf` would send same notification to server after initialization response is dropped.\n\n### List Changed\n\nAfter server restarts, it might have new tools, prompts or resources. \n\n`synf` would notify client to repeat requests by sending such notifications:\n\n```json\n{\"method\":\"notifications/tools/list_changed\",\"jsonrpc\":\"2.0\"}\n{\"method\":\"notifications/prompts/list_changed\",\"jsonrpc\":\"2.0\"}\n{\"method\":\"notifications/resources/list_changed\",\"jsonrpc\":\"2.0\"}\n```\n\nNote that some clients might be bugged at the moment and would ignore these notifications, so you might need to manually restart them until the client is following specification correctly.\n\n### Subscriptions\n\nThe protocol supports optional subscriptions to resource changes. \nClients can subscribe to specific resources and receive notifications when they change:\n\nSubscribe Request:\n\n```json\n{\n  \"jsonrpc\": \"2.0\",\n  \"id\": 4,\n  \"method\": \"resources/subscribe\",\n  \"params\": {\n    \"uri\": \"file:///project/src/main.rs\"\n  }\n}\n```\n\nUpdate Notification:\n\n\n```json\n{\n  \"jsonrpc\": \"2.0\",\n  \"method\": \"notifications/resources/updated\",\n  \"params\": {\n    \"uri\": \"file:///project/src/main.rs\"\n  }\n}\n```\n\n`synf` can cache the resources subscribed to and would resend the subscriptions to server after restart.","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fstrowk%2Fsynf","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fstrowk%2Fsynf","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fstrowk%2Fsynf/lists"}