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.
- forscore_mcp-1.0.0/LICENSE +75 -0
- forscore_mcp-1.0.0/PKG-INFO +270 -0
- forscore_mcp-1.0.0/README.md +248 -0
- forscore_mcp-1.0.0/pyproject.toml +74 -0
- forscore_mcp-1.0.0/pyproject.toml.orig +59 -0
- forscore_mcp-1.0.0/src/forscore_mcp/__init__.py +11 -0
- forscore_mcp-1.0.0/src/forscore_mcp/audit.py +88 -0
- forscore_mcp-1.0.0/src/forscore_mcp/changeset.py +225 -0
- forscore_mcp-1.0.0/src/forscore_mcp/cli.py +301 -0
- forscore_mcp-1.0.0/src/forscore_mcp/conventions.md +43 -0
- forscore_mcp-1.0.0/src/forscore_mcp/csvimport.py +176 -0
- forscore_mcp-1.0.0/src/forscore_mcp/db.py +61 -0
- forscore_mcp-1.0.0/src/forscore_mcp/doctor.py +94 -0
- forscore_mcp-1.0.0/src/forscore_mcp/errors.py +29 -0
- forscore_mcp-1.0.0/src/forscore_mcp/keys.py +63 -0
- forscore_mcp-1.0.0/src/forscore_mcp/library.py +265 -0
- forscore_mcp-1.0.0/src/forscore_mcp/models.py +108 -0
- forscore_mcp-1.0.0/src/forscore_mcp/paths.py +37 -0
- forscore_mcp-1.0.0/src/forscore_mcp/repository.py +393 -0
- forscore_mcp-1.0.0/src/forscore_mcp/safety.py +129 -0
- forscore_mcp-1.0.0/src/forscore_mcp/schema.py +114 -0
- forscore_mcp-1.0.0/src/forscore_mcp/server.py +200 -0
- forscore_mcp-1.0.0/src/forscore_mcp/sorttitle.py +10 -0
- forscore_mcp-1.0.0/src/forscore_mcp/syncfiles.py +162 -0
|
@@ -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"]
|