forscore-mcp 1.0.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,75 @@
1
+ # PolyForm Noncommercial License 1.0.0
2
+
3
+ <https://polyformproject.org/licenses/noncommercial/1.0.0>
4
+
5
+ ## Acceptance
6
+
7
+ In order to get any license under these terms, you must agree to them as both strict obligations and conditions to all your licenses.
8
+
9
+ ## Copyright License
10
+
11
+ The licensor grants you a copyright license for the software to do everything you might do with the software that would otherwise infringe the licensor's copyright in it for any permitted purpose. However, you may only distribute the software according to [Distribution License](#distribution-license) and make changes or new works based on the software according to [Changes and New Works License](#changes-and-new-works-license).
12
+
13
+ ## Distribution License
14
+
15
+ The licensor grants you an additional copyright license to distribute copies of the software. Your license to distribute covers distributing the software with changes and new works permitted by [Changes and New Works License](#changes-and-new-works-license).
16
+
17
+ ## Notices
18
+
19
+ You must ensure that anyone who gets a copy of any part of the software from you also gets a copy of these terms or the URL for them above, as well as copies of any plain-text lines beginning with `Required Notice:` that the licensor provided with the software. For example:
20
+
21
+ > Required Notice: Copyright Yoyodyne, Inc. (http://example.com)
22
+
23
+ ## Changes and New Works License
24
+
25
+ The licensor grants you an additional copyright license to make changes and new works based on the software for any permitted purpose.
26
+
27
+ ## Patent License
28
+
29
+ The licensor grants you a patent license for the software that covers patent claims the licensor can license, or becomes able to license, that you would infringe by using the software.
30
+
31
+ ## Noncommercial Purposes
32
+
33
+ Any noncommercial purpose is a permitted purpose.
34
+
35
+ ## Personal Uses
36
+
37
+ Personal use for research, experiment, and testing for the benefit of public knowledge, personal study, private entertainment, hobby projects, amateur pursuits, or religious observance, without any anticipated commercial application, is use for a permitted purpose.
38
+
39
+ ## Noncommercial Organizations
40
+
41
+ Use by any charitable organization, educational institution, public research organization, public safety or health organization, environmental protection organization, or government institution is use for a permitted purpose regardless of the source of funding or obligations resulting from the funding.
42
+
43
+ ## Fair Use
44
+
45
+ You may have "fair use" rights for the software under the law. These terms do not limit them.
46
+
47
+ ## No Other Rights
48
+
49
+ These terms do not allow you to sublicense or transfer any of your licenses to anyone else, or prevent the licensor from granting licenses to anyone else. These terms do not imply any other licenses.
50
+
51
+ ## Patent Defense
52
+
53
+ If you make any written claim that the software infringes or contributes to infringement of any patent, your patent license for the software granted under these terms ends immediately. If your company makes such a claim, your patent license ends immediately for work on behalf of your company.
54
+
55
+ ## Violations
56
+
57
+ The first time you are notified in writing that you have violated any of these terms, or done anything with the software not covered by your licenses, your licenses can nonetheless continue if you come into full compliance with these terms, and take practical steps to correct past violations, within 32 days of receiving notice. Otherwise, all your licenses end immediately.
58
+
59
+ ## No Liability
60
+
61
+ ***As far as the law allows, the software comes as is, without any warranty or condition, and the licensor will not be liable to you for any damages arising out of these terms or the use or nature of the software, under any kind of legal claim.***
62
+
63
+ ## Definitions
64
+
65
+ The **licensor** is the individual or entity offering these terms, and the **software** is the software the licensor makes available under these terms.
66
+
67
+ **You** refers to the individual or entity agreeing to these terms.
68
+
69
+ **Your company** is any legal entity, sole proprietorship, or other kind of organization that you work for, plus all organizations that have control over, are under the control of, or are under common control with that organization. **Control** means ownership of substantially all the assets of an entity, or the power to direct its management and policies by vote, contract, or otherwise. Control can be direct or indirect.
70
+
71
+ **Your licenses** are all the licenses granted to you for the software under these terms.
72
+
73
+ **Use** means anything you do with the software requiring one of your licenses.
74
+
75
+ Required Notice: Copyright Soham Chatterjee (https://github.com/Soham-Chatt)
@@ -0,0 +1,270 @@
1
+ Metadata-Version: 2.4
2
+ Name: forscore-mcp
3
+ Version: 1.0.0
4
+ Summary: Read and clean up forScore library metadata from the CLI, an MCP server, or an LLM skill
5
+ Keywords: forscore,mcp,sheet-music,claude,llm
6
+ Author: Soham
7
+ Author-email: Soham <113625563+Soham-Chatt@users.noreply.github.com>
8
+ License-Expression: PolyForm-Noncommercial-1.0.0
9
+ License-File: LICENSE
10
+ Classifier: Development Status :: 4 - Beta
11
+ Classifier: Environment :: Console
12
+ Classifier: Intended Audience :: End Users/Desktop
13
+ Classifier: Operating System :: MacOS
14
+ Classifier: Programming Language :: Python :: 3
15
+ Classifier: Topic :: Multimedia :: Sound/Audio
16
+ Requires-Dist: mcp>=2.3,<3
17
+ Requires-Python: >=3.12
18
+ Project-URL: Homepage, https://github.com/Soham-Chatt/forscore-mcp
19
+ Project-URL: Documentation, https://github.com/Soham-Chatt/forscore-mcp/blob/main/docs/reference.md
20
+ Project-URL: Issues, https://github.com/Soham-Chatt/forscore-mcp/issues
21
+ Description-Content-Type: text/markdown
22
+
23
+ # forscore-mcp
24
+
25
+ <!-- mcp-name: io.github.Soham-Chatt/forscore-mcp -->
26
+
27
+ Clean up the metadata in a [forScore](https://forscore.co) sheet-music library in bulk:
28
+ titles, composers, catalogue references (Op., BWV, K., …), keys, genres, tags, ratings and more.
29
+ It works through an AI assistant (an MCP server and a Claude Code plugin; Claude and other
30
+ LLMs) or from the command line.
31
+
32
+ > **Not affiliated with or endorsed by forScore LLC.** forScore is a trademark of forScore LLC.
33
+ > The tool reads forScore's internal library database, which is not a public API, and writes
34
+ > changes through forScore's own Metadata CSV import, as forScore's support recommends. Data
35
+ > is still injected into forScore as-is, and the tool cannot guarantee that it works
36
+ > correctly or preserves existing data. Always check forScore's import preview before tapping
37
+ > Save.
38
+
39
+ ## Features
40
+
41
+ - **Read**:
42
+ - every score and bookmark with its metadata (filtered and paged for large libraries)
43
+ - every composer, genre, tag, label and library in use
44
+ - setlists
45
+ - **Bulk-edit** titles, composers, references, keys, genres, tags, labels, rating,
46
+ difficulty and duration, for scores and bookmarks.
47
+ - **Rename or merge** a composer, genre or tag everywhere it is used.
48
+ - **Audit** for likely duplicates, identical PDFs, file names that differ from titles, and
49
+ composer sort names worth checking.
50
+ - **Check sync**: compare the library with what synced devices receive.
51
+ - **Conventions guide** for AI assistants, so their edits stay consistent: full composer
52
+ names, `Op. 69 No. 2` references, genre as style period. See
53
+ [`conventions.md`](src/forscore_mcp/conventions.md).
54
+
55
+ ## How it works
56
+
57
+ 1. **Read:** the tool opens forScore's library database on the Mac read-only and checks its
58
+ layout every time. It refuses to work with anything it does not recognise.
59
+ 2. **Propose:** the assistant (or you) writes a *changeset*, a small JSON description of the
60
+ changes. It is previewed as a per-score diff, and nothing is written yet.
61
+ 3. **Import:** the changeset becomes a CSV in forScore's own Metadata format, and the tool
62
+ hands it to forScore. In forScore, open **Backups › Metadata (CSV) › Import**, tap the file,
63
+ check forScore's preview and tap **Save**. forScore applies it and syncs it to your other
64
+ devices.
65
+ 4. **Verify or undo:** the tool checks field by field that the import applied. Any import can
66
+ be reverted with a second, generated CSV.
67
+
68
+ forScore can stay open throughout.
69
+
70
+ ## Requirements
71
+
72
+ - A Mac with forScore. The library database only exists on the Mac; iPad-only setups are not
73
+ supported.
74
+ - [uv](https://docs.astral.sh/uv/getting-started/installation/) (`brew install uv`).
75
+ - **Full Disk Access** for the app that runs the tool (Terminal, Claude, Cursor, …), because
76
+ forScore's data sits in a protected app container: System Settings › Privacy & Security ›
77
+ Full Disk Access.
78
+
79
+ ## Install
80
+
81
+ ### Claude Code (plugin: MCP server + skill)
82
+
83
+ ```
84
+ /plugin install forscore --marketplace Soham-Chatt/forscore-mcp
85
+ ```
86
+
87
+ Or from a shell: `claude plugin install forscore --marketplace Soham-Chatt/forscore-mcp`.
88
+ On older Claude Code versions, run `/plugin marketplace add Soham-Chatt/forscore-mcp` and then
89
+ `/plugin install forscore@forscore-mcp`.
90
+
91
+ Update with `claude plugin update forscore@forscore-mcp`, or turn on auto-update under
92
+ **Marketplaces** in `/plugin`. The plugin needs Claude Code, or Claude Desktop through the
93
+ MCP configuration below. claude.ai on the web and Cowork cannot reach a Mac's local library.
94
+
95
+ ### Other MCP clients (Claude Desktop, Cursor, VS Code, Codex, Gemini CLI, …)
96
+
97
+ Add the server to the client's MCP configuration. For Claude Desktop that is
98
+ `~/Library/Application Support/Claude/claude_desktop_config.json`:
99
+
100
+ ```json
101
+ {
102
+ "mcpServers": {
103
+ "forscore": {
104
+ "command": "uvx",
105
+ "args": ["forscore-mcp"]
106
+ }
107
+ }
108
+ }
109
+ ```
110
+
111
+ It is also listed in the [official MCP registry](https://registry.modelcontextprotocol.io) as
112
+ `io.github.Soham-Chatt/forscore-mcp`. Agents without MCP support can use the CLI with `--json`;
113
+ see [`AGENTS.md`](AGENTS.md).
114
+
115
+ ### Command line
116
+
117
+ ```
118
+ uv tool install forscore-mcp
119
+ forscore-mcp doctor
120
+ ```
121
+
122
+ `doctor` checks library access, sync state and the write mode, and explains how to fix any
123
+ problem it finds.
124
+
125
+ ## Usage
126
+
127
+ Ask the assistant things like *"Clean up the composers in my forScore library"* or *"Fill in
128
+ the opus numbers for my Chopin scores"*. It follows the bundled
129
+ [conventions guide](src/forscore_mcp/conventions.md) unless told otherwise, and proposes a
130
+ table of changes. Once you approve them, it previews them and creates the import for
131
+ forScore.
132
+
133
+ Command line:
134
+
135
+ ```
136
+ forscore-mcp list chopin # search scores and bookmarks
137
+ forscore-mcp list --missing composers # filters: --composer --genre --tag --library --kind
138
+ forscore-mcp show "Kinderszenen > Träumerei" # one score or bookmark
139
+ forscore-mcp values composers # values in use, with counts and sort names
140
+ forscore-mcp setlists # setlists and their items
141
+ forscore-mcp audit # likely duplicates, file names, sort names
142
+ forscore-mcp preview changes.json # dry run of a changeset
143
+ forscore-mcp apply changes.json --yes # create the import CSV and hand it to forScore
144
+ forscore-mcp verify <import id> # after Save in forScore: did everything apply?
145
+ forscore-mcp undo <import id> --yes # a CSV that restores the previous values
146
+ forscore-mcp sync-check # do synced devices get the same metadata?
147
+ forscore-mcp key "E♭ major" # key name ↔ forScore's internal code
148
+ ```
149
+
150
+ Add `--json` to any command for machine-readable output.
151
+
152
+ ### Changesets
153
+
154
+ See [`examples/changeset.example.json`](examples/changeset.example.json):
155
+
156
+ ```json
157
+ {
158
+ "renames": { "composers": { "Chopin": "Frédéric Chopin" } },
159
+ "items": [
160
+ { "match": "Fur Elise",
161
+ "set": { "title": "Für Elise", "reference": "WoO 59", "key": "A minor", "genres": ["Classical"] },
162
+ "add": { "tags": ["ABRSM Grade 5"] } },
163
+ { "match": "Kinderszenen › Träumerei", "set": { "reference": "Op. 15 No. 7" } }
164
+ ]
165
+ }
166
+ ```
167
+
168
+ - `match`: a UUID, an exact title, or `"Score › Bookmark"` (`>` works too).
169
+ - `set` replaces these fields: `title`, `reference`, `key`, `rating` (0–5), `difficulty`
170
+ (0–3), `duration` (`"m:ss"`), `composers`, `genres`, `tags` and `labels`.
171
+ - `add` and `remove` edit the list fields.
172
+ - `renames` renames a value everywhere it is used.
173
+
174
+ ### What the CSV import cannot do
175
+
176
+ forScore's CSV format has no columns for these, so the tool lists them under "not in CSV"
177
+ instead of importing them:
178
+ - scores that have bookmarks, and bookmarks themselves: forScore's CSV import does not match
179
+ existing bookmarks reliably and can delete or duplicate them
180
+ - library membership
181
+ - composer sort names (`sort_names`)
182
+ - keys with more than 7 sharps or flats
183
+ - values containing a comma
184
+ - changing PDF file names
185
+
186
+ Make these changes in forScore itself. Changing a title in forScore can rename the PDF to
187
+ match.
188
+
189
+ ### MCP tools
190
+
191
+ Every tool's parameters and the full CLI are listed in [`docs/reference.md`](docs/reference.md),
192
+ which is generated from the code.
193
+
194
+ | Tool | Effect |
195
+ |---|---|
196
+ | `list_scores` (filters, paging), `get_score`, `list_values`, `list_setlists`, `audit_library`, `check_sync`, `convert_key`, `doctor`, `get_conventions` | read only |
197
+ | `preview_changeset` | read only (dry run) |
198
+ | `apply_changeset(changeset, confirm=true)`, `undo_import(import_id, confirm=true)` | creates an import CSV for review in forScore |
199
+ | `verify_import(import_id)` | read only |
200
+ | `create_backup`, `list_backups` | copies of the library database |
201
+ | `apply_changeset(method="direct")`, `restore_backup` | only with direct writes on (below) |
202
+
203
+ Environment variables:
204
+ - `FORSCORE_LIBRARY`: path to the library database.
205
+ - `FORSCORE_STATE_DIR`: where import CSVs are kept. The default is
206
+ `~/Library/Application Support/forscore-mcp`.
207
+ - `FORSCORE_BACKUP_DIR`: where backups go.
208
+
209
+ ## Direct writes (unsupported by forScore)
210
+
211
+ > **Can cause crashes, unexpected behaviour or data loss.** forScore's developers advise against
212
+ > it. It bypasses forScore's own validation and edits the database and the per-score sync files
213
+ > directly.
214
+
215
+ For the changes the CSV import cannot make (scores with bookmarks, library membership,
216
+ composer sort names), the
217
+ tool can write the database directly. This is off by default. Turn it on with a confirmation
218
+ phrase:
219
+
220
+ ```
221
+ forscore-mcp direct-writes enable i-understand-this-can-damage-my-library
222
+ forscore-mcp direct-writes status
223
+ forscore-mcp direct-writes disable
224
+ ```
225
+
226
+ The setting is stored in `~/Library/Application Support/forscore-mcp/config.json` and takes
227
+ effect immediately, including for a running MCP server. Instead, the variable
228
+ `FORSCORE_DIRECT_WRITES=i-understand-this-can-damage-my-library` can be set in an MCP client's
229
+ `env` configuration.
230
+
231
+ While it is on:
232
+ - A write is only direct when asked for: `apply_changeset(..., method="direct")` or
233
+ `forscore-mcp apply --direct --yes`. Everything else still goes through the CSV import.
234
+ - forScore must be quit on the Mac during direct writes, and a backup is made first.
235
+ - `restore` puts a backup back.
236
+ - Values nothing uses any more are deleted. forScore hides them anyway, and each device keeps
237
+ its own list.
238
+ - `doctor` shows that direct writes are on.
239
+
240
+ No MCP tool can turn direct writes on.
241
+
242
+ ## Limitations
243
+
244
+ - macOS only.
245
+ - Early (0.x), tested with forScore 15.2. A forScore update that changes the database layout
246
+ makes the tool refuse to run until it is updated.
247
+ - Setlists are read-only.
248
+
249
+ ## Contributing
250
+
251
+ Issues and pull requests are welcome, including reports from other forScore versions and
252
+ setups. See [`CONTRIBUTING.md`](CONTRIBUTING.md).
253
+
254
+ Development:
255
+
256
+ ```
257
+ uv sync
258
+ uv run pytest # tests use a synthetic library, never a real one
259
+ uv run ruff check . && uv run ruff format . && uv run ty check
260
+ ```
261
+
262
+ [`AGENTS.md`](AGENTS.md) describes the architecture and rules; [`docs/schema.md`](docs/schema.md)
263
+ documents what is known about forScore's storage; [`docs/releasing.md`](docs/releasing.md)
264
+ covers releases.
265
+
266
+ ## License
267
+
268
+ [PolyForm Noncommercial 1.0.0](LICENSE): free for personal and other non-commercial use,
269
+ including changing and sharing it. Commercial use requires a separate license; open an issue or
270
+ contact the author to ask.
@@ -0,0 +1,248 @@
1
+ # forscore-mcp
2
+
3
+ <!-- mcp-name: io.github.Soham-Chatt/forscore-mcp -->
4
+
5
+ Clean up the metadata in a [forScore](https://forscore.co) sheet-music library in bulk:
6
+ titles, composers, catalogue references (Op., BWV, K., …), keys, genres, tags, ratings and more.
7
+ It works through an AI assistant (an MCP server and a Claude Code plugin; Claude and other
8
+ LLMs) or from the command line.
9
+
10
+ > **Not affiliated with or endorsed by forScore LLC.** forScore is a trademark of forScore LLC.
11
+ > The tool reads forScore's internal library database, which is not a public API, and writes
12
+ > changes through forScore's own Metadata CSV import, as forScore's support recommends. Data
13
+ > is still injected into forScore as-is, and the tool cannot guarantee that it works
14
+ > correctly or preserves existing data. Always check forScore's import preview before tapping
15
+ > Save.
16
+
17
+ ## Features
18
+
19
+ - **Read**:
20
+ - every score and bookmark with its metadata (filtered and paged for large libraries)
21
+ - every composer, genre, tag, label and library in use
22
+ - setlists
23
+ - **Bulk-edit** titles, composers, references, keys, genres, tags, labels, rating,
24
+ difficulty and duration, for scores and bookmarks.
25
+ - **Rename or merge** a composer, genre or tag everywhere it is used.
26
+ - **Audit** for likely duplicates, identical PDFs, file names that differ from titles, and
27
+ composer sort names worth checking.
28
+ - **Check sync**: compare the library with what synced devices receive.
29
+ - **Conventions guide** for AI assistants, so their edits stay consistent: full composer
30
+ names, `Op. 69 No. 2` references, genre as style period. See
31
+ [`conventions.md`](src/forscore_mcp/conventions.md).
32
+
33
+ ## How it works
34
+
35
+ 1. **Read:** the tool opens forScore's library database on the Mac read-only and checks its
36
+ layout every time. It refuses to work with anything it does not recognise.
37
+ 2. **Propose:** the assistant (or you) writes a *changeset*, a small JSON description of the
38
+ changes. It is previewed as a per-score diff, and nothing is written yet.
39
+ 3. **Import:** the changeset becomes a CSV in forScore's own Metadata format, and the tool
40
+ hands it to forScore. In forScore, open **Backups › Metadata (CSV) › Import**, tap the file,
41
+ check forScore's preview and tap **Save**. forScore applies it and syncs it to your other
42
+ devices.
43
+ 4. **Verify or undo:** the tool checks field by field that the import applied. Any import can
44
+ be reverted with a second, generated CSV.
45
+
46
+ forScore can stay open throughout.
47
+
48
+ ## Requirements
49
+
50
+ - A Mac with forScore. The library database only exists on the Mac; iPad-only setups are not
51
+ supported.
52
+ - [uv](https://docs.astral.sh/uv/getting-started/installation/) (`brew install uv`).
53
+ - **Full Disk Access** for the app that runs the tool (Terminal, Claude, Cursor, …), because
54
+ forScore's data sits in a protected app container: System Settings › Privacy & Security ›
55
+ Full Disk Access.
56
+
57
+ ## Install
58
+
59
+ ### Claude Code (plugin: MCP server + skill)
60
+
61
+ ```
62
+ /plugin install forscore --marketplace Soham-Chatt/forscore-mcp
63
+ ```
64
+
65
+ Or from a shell: `claude plugin install forscore --marketplace Soham-Chatt/forscore-mcp`.
66
+ On older Claude Code versions, run `/plugin marketplace add Soham-Chatt/forscore-mcp` and then
67
+ `/plugin install forscore@forscore-mcp`.
68
+
69
+ Update with `claude plugin update forscore@forscore-mcp`, or turn on auto-update under
70
+ **Marketplaces** in `/plugin`. The plugin needs Claude Code, or Claude Desktop through the
71
+ MCP configuration below. claude.ai on the web and Cowork cannot reach a Mac's local library.
72
+
73
+ ### Other MCP clients (Claude Desktop, Cursor, VS Code, Codex, Gemini CLI, …)
74
+
75
+ Add the server to the client's MCP configuration. For Claude Desktop that is
76
+ `~/Library/Application Support/Claude/claude_desktop_config.json`:
77
+
78
+ ```json
79
+ {
80
+ "mcpServers": {
81
+ "forscore": {
82
+ "command": "uvx",
83
+ "args": ["forscore-mcp"]
84
+ }
85
+ }
86
+ }
87
+ ```
88
+
89
+ It is also listed in the [official MCP registry](https://registry.modelcontextprotocol.io) as
90
+ `io.github.Soham-Chatt/forscore-mcp`. Agents without MCP support can use the CLI with `--json`;
91
+ see [`AGENTS.md`](AGENTS.md).
92
+
93
+ ### Command line
94
+
95
+ ```
96
+ uv tool install forscore-mcp
97
+ forscore-mcp doctor
98
+ ```
99
+
100
+ `doctor` checks library access, sync state and the write mode, and explains how to fix any
101
+ problem it finds.
102
+
103
+ ## Usage
104
+
105
+ Ask the assistant things like *"Clean up the composers in my forScore library"* or *"Fill in
106
+ the opus numbers for my Chopin scores"*. It follows the bundled
107
+ [conventions guide](src/forscore_mcp/conventions.md) unless told otherwise, and proposes a
108
+ table of changes. Once you approve them, it previews them and creates the import for
109
+ forScore.
110
+
111
+ Command line:
112
+
113
+ ```
114
+ forscore-mcp list chopin # search scores and bookmarks
115
+ forscore-mcp list --missing composers # filters: --composer --genre --tag --library --kind
116
+ forscore-mcp show "Kinderszenen > Träumerei" # one score or bookmark
117
+ forscore-mcp values composers # values in use, with counts and sort names
118
+ forscore-mcp setlists # setlists and their items
119
+ forscore-mcp audit # likely duplicates, file names, sort names
120
+ forscore-mcp preview changes.json # dry run of a changeset
121
+ forscore-mcp apply changes.json --yes # create the import CSV and hand it to forScore
122
+ forscore-mcp verify <import id> # after Save in forScore: did everything apply?
123
+ forscore-mcp undo <import id> --yes # a CSV that restores the previous values
124
+ forscore-mcp sync-check # do synced devices get the same metadata?
125
+ forscore-mcp key "E♭ major" # key name ↔ forScore's internal code
126
+ ```
127
+
128
+ Add `--json` to any command for machine-readable output.
129
+
130
+ ### Changesets
131
+
132
+ See [`examples/changeset.example.json`](examples/changeset.example.json):
133
+
134
+ ```json
135
+ {
136
+ "renames": { "composers": { "Chopin": "Frédéric Chopin" } },
137
+ "items": [
138
+ { "match": "Fur Elise",
139
+ "set": { "title": "Für Elise", "reference": "WoO 59", "key": "A minor", "genres": ["Classical"] },
140
+ "add": { "tags": ["ABRSM Grade 5"] } },
141
+ { "match": "Kinderszenen › Träumerei", "set": { "reference": "Op. 15 No. 7" } }
142
+ ]
143
+ }
144
+ ```
145
+
146
+ - `match`: a UUID, an exact title, or `"Score › Bookmark"` (`>` works too).
147
+ - `set` replaces these fields: `title`, `reference`, `key`, `rating` (0–5), `difficulty`
148
+ (0–3), `duration` (`"m:ss"`), `composers`, `genres`, `tags` and `labels`.
149
+ - `add` and `remove` edit the list fields.
150
+ - `renames` renames a value everywhere it is used.
151
+
152
+ ### What the CSV import cannot do
153
+
154
+ forScore's CSV format has no columns for these, so the tool lists them under "not in CSV"
155
+ instead of importing them:
156
+ - scores that have bookmarks, and bookmarks themselves: forScore's CSV import does not match
157
+ existing bookmarks reliably and can delete or duplicate them
158
+ - library membership
159
+ - composer sort names (`sort_names`)
160
+ - keys with more than 7 sharps or flats
161
+ - values containing a comma
162
+ - changing PDF file names
163
+
164
+ Make these changes in forScore itself. Changing a title in forScore can rename the PDF to
165
+ match.
166
+
167
+ ### MCP tools
168
+
169
+ Every tool's parameters and the full CLI are listed in [`docs/reference.md`](docs/reference.md),
170
+ which is generated from the code.
171
+
172
+ | Tool | Effect |
173
+ |---|---|
174
+ | `list_scores` (filters, paging), `get_score`, `list_values`, `list_setlists`, `audit_library`, `check_sync`, `convert_key`, `doctor`, `get_conventions` | read only |
175
+ | `preview_changeset` | read only (dry run) |
176
+ | `apply_changeset(changeset, confirm=true)`, `undo_import(import_id, confirm=true)` | creates an import CSV for review in forScore |
177
+ | `verify_import(import_id)` | read only |
178
+ | `create_backup`, `list_backups` | copies of the library database |
179
+ | `apply_changeset(method="direct")`, `restore_backup` | only with direct writes on (below) |
180
+
181
+ Environment variables:
182
+ - `FORSCORE_LIBRARY`: path to the library database.
183
+ - `FORSCORE_STATE_DIR`: where import CSVs are kept. The default is
184
+ `~/Library/Application Support/forscore-mcp`.
185
+ - `FORSCORE_BACKUP_DIR`: where backups go.
186
+
187
+ ## Direct writes (unsupported by forScore)
188
+
189
+ > **Can cause crashes, unexpected behaviour or data loss.** forScore's developers advise against
190
+ > it. It bypasses forScore's own validation and edits the database and the per-score sync files
191
+ > directly.
192
+
193
+ For the changes the CSV import cannot make (scores with bookmarks, library membership,
194
+ composer sort names), the
195
+ tool can write the database directly. This is off by default. Turn it on with a confirmation
196
+ phrase:
197
+
198
+ ```
199
+ forscore-mcp direct-writes enable i-understand-this-can-damage-my-library
200
+ forscore-mcp direct-writes status
201
+ forscore-mcp direct-writes disable
202
+ ```
203
+
204
+ The setting is stored in `~/Library/Application Support/forscore-mcp/config.json` and takes
205
+ effect immediately, including for a running MCP server. Instead, the variable
206
+ `FORSCORE_DIRECT_WRITES=i-understand-this-can-damage-my-library` can be set in an MCP client's
207
+ `env` configuration.
208
+
209
+ While it is on:
210
+ - A write is only direct when asked for: `apply_changeset(..., method="direct")` or
211
+ `forscore-mcp apply --direct --yes`. Everything else still goes through the CSV import.
212
+ - forScore must be quit on the Mac during direct writes, and a backup is made first.
213
+ - `restore` puts a backup back.
214
+ - Values nothing uses any more are deleted. forScore hides them anyway, and each device keeps
215
+ its own list.
216
+ - `doctor` shows that direct writes are on.
217
+
218
+ No MCP tool can turn direct writes on.
219
+
220
+ ## Limitations
221
+
222
+ - macOS only.
223
+ - Early (0.x), tested with forScore 15.2. A forScore update that changes the database layout
224
+ makes the tool refuse to run until it is updated.
225
+ - Setlists are read-only.
226
+
227
+ ## Contributing
228
+
229
+ Issues and pull requests are welcome, including reports from other forScore versions and
230
+ setups. See [`CONTRIBUTING.md`](CONTRIBUTING.md).
231
+
232
+ Development:
233
+
234
+ ```
235
+ uv sync
236
+ uv run pytest # tests use a synthetic library, never a real one
237
+ uv run ruff check . && uv run ruff format . && uv run ty check
238
+ ```
239
+
240
+ [`AGENTS.md`](AGENTS.md) describes the architecture and rules; [`docs/schema.md`](docs/schema.md)
241
+ documents what is known about forScore's storage; [`docs/releasing.md`](docs/releasing.md)
242
+ covers releases.
243
+
244
+ ## License
245
+
246
+ [PolyForm Noncommercial 1.0.0](LICENSE): free for personal and other non-commercial use,
247
+ including changing and sharing it. Commercial use requires a separate license; open an issue or
248
+ contact the author to ask.
@@ -0,0 +1,74 @@
1
+ [project]
2
+ name = "forscore-mcp"
3
+ version = "1.0.0"
4
+ description = "Read and clean up forScore library metadata from the CLI, an MCP server, or an LLM skill"
5
+ readme = "README.md"
6
+ license = "PolyForm-Noncommercial-1.0.0"
7
+ license-files = ["LICENSE"]
8
+ requires-python = ">=3.12"
9
+ keywords = [
10
+ "forscore",
11
+ "mcp",
12
+ "sheet-music",
13
+ "claude",
14
+ "llm",
15
+ ]
16
+ classifiers = [
17
+ "Development Status :: 4 - Beta",
18
+ "Environment :: Console",
19
+ "Intended Audience :: End Users/Desktop",
20
+ "Operating System :: MacOS",
21
+ "Programming Language :: Python :: 3",
22
+ "Topic :: Multimedia :: Sound/Audio",
23
+ ]
24
+ dependencies = ["mcp>=2.3,<3"]
25
+
26
+ [[project.authors]]
27
+ name = "Soham"
28
+ email = "113625563+Soham-Chatt@users.noreply.github.com"
29
+
30
+ [project.urls]
31
+ Homepage = "https://github.com/Soham-Chatt/forscore-mcp"
32
+ Documentation = "https://github.com/Soham-Chatt/forscore-mcp/blob/main/docs/reference.md"
33
+ Issues = "https://github.com/Soham-Chatt/forscore-mcp/issues"
34
+
35
+ [project.scripts]
36
+ forscore-mcp = "forscore_mcp.cli:main"
37
+
38
+ [build-system]
39
+ requires = ["uv_build>=0.12.19,<0.14.0"]
40
+ build-backend = "uv_build"
41
+
42
+ [dependency-groups]
43
+ dev = [
44
+ "pytest>=9.1.1",
45
+ "pytest-cov>=7.1.0",
46
+ "ruff>=0.17.2",
47
+ "ty>=0.0.91",
48
+ ]
49
+
50
+ [tool.ruff]
51
+ line-length = 100
52
+ target-version = "py312"
53
+
54
+ [tool.ruff.lint]
55
+ select = [
56
+ "E",
57
+ "F",
58
+ "I",
59
+ "B",
60
+ "UP",
61
+ "SIM",
62
+ "RUF",
63
+ ]
64
+ allowed-confusables = [
65
+ "›",
66
+ "’",
67
+ ]
68
+
69
+ [tool.pytest.ini_options]
70
+ testpaths = ["tests"]
71
+ addopts = "-q"
72
+
73
+ [tool.coverage.run]
74
+ source = ["forscore_mcp"]