Skip to content

Commit f846f4c

Browse files
TMHSDigitalclaude
andcommitted
CLI and MCP server over data.json (#115)
- lib/catalog-query.mjs: searchAssets, getAsset, checkLicense and listStacks over data.json, reusing the site's search, engine and listed rules; answers carry licence, commercial use, credit line, engine lock, status and open question, verified date and the entry page - site/cli/fgda.mjs (package.json bin "fgda"): search / get / check / stacks, --json, --data <file|https URL>; check exits 1 when an entry does not fit, for CI. Works as npx github:TMHSDigital/Free-Game-Dev-Assets - site/cli/mcp.mjs: a zero-dependency stdio MCP server (JSON-RPC 2.0, tools only): search_assets, get_asset, check_license, list_stacks - docs/data.md has the commands and an MCP client config; README links it Not done: publishing to npm (needs the owner's npm account), so no bare `npx free-game-dev-assets`; not tried in a desktop MCP client here, only over stdio and in tests. Closes #115 Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01LpkeXQPaUhxjgqdqnk6BrJ
1 parent b17a8b6 commit f846f4c

8 files changed

Lines changed: 394 additions & 1 deletion

File tree

‎README.md‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -212,7 +212,8 @@ line for each entry, an Atom [feed of new sources](https://tmhsdigital.github.io
212212
a [feed of re-verified licences](https://tmhsdigital.github.io/Free-Game-Dev-Assets/reverified.xml) and
213213
[`llms.txt`](https://tmhsdigital.github.io/Free-Game-Dev-Assets/llms.txt). Pin a version from
214214
[Releases](https://github.com/TMHSDigital/Free-Game-Dev-Assets/releases). [`docs/data.md`](docs/data.md)
215-
has the field reference, `jq` and pandas examples, and how to cite it (`CITATION.cff`).
215+
has the field reference, `jq` and pandas examples, how to cite it (`CITATION.cff`), a CLI
216+
(`npx github:TMHSDigital/Free-Game-Dev-Assets search "pixel font" --license cc0`) and an MCP server for assistants.
216217

217218
## Scope
218219

‎docs/data.md‎

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -71,6 +71,27 @@ print(ok[["name", "license", "attribution_required", "attribution_string", "url"
7171

7272
Follow new sources in any feed reader by subscribing to `https://tmhsdigital.github.io/Free-Game-Dev-Assets/feed.xml`.
7373

74+
## From a shell, CI or an assistant
75+
76+
`site/cli/fgda.mjs` queries the same data with the site's search and filters, no install:
77+
78+
```bash
79+
npx github:TMHSDigital/Free-Game-Dev-Assets search "pixel font" --license "SIL OFL" --commercial
80+
npx github:TMHSDigital/Free-Game-Dev-Assets check kenney --engine godot # exit 1 if it does not fit
81+
npx github:TMHSDigital/Free-Game-Dev-Assets get incompetech --json
82+
```
83+
84+
`check` exits 1 when the entry is not for commercial use, is locked to another engine, varies per file, or is
85+
still `needs-review` (with its open question), so a build can stop on it. In a clone, `node site/cli/fgda.mjs`
86+
does the same and reads `site/dist/data.json` when a build is there; `--data <file or https URL>` picks another copy.
87+
88+
`site/cli/mcp.mjs` is a Model Context Protocol server (stdio, no dependencies) with the tools `search_assets`,
89+
`get_asset`, `check_license` and `list_stacks`. In Claude Desktop, Cursor or another MCP client, from a clone:
90+
91+
```json
92+
{ "mcpServers": { "free-game-dev-assets": { "command": "node", "args": ["/path/to/Free-Game-Dev-Assets/site/cli/mcp.mjs"] } } }
93+
```
94+
7495
## How to cite
7596

7697
The repository has a [`CITATION.cff`](../CITATION.cff), and GitHub's "Cite this repository" button renders it. In text:

‎package.json‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -3,6 +3,9 @@
33
"private": true,
44
"description": "Catalog checks and static site build. No dependencies.",
55
"license": "CC0-1.0",
6+
"bin": {
7+
"fgda": "site/cli/fgda.mjs"
8+
},
69
"engines": {
710
"node": ">=22"
811
},

‎site/cli/data.mjs‎

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
/**
2+
* Loads data.json for the CLI and the MCP server: a local file or URL from
3+
* `--data` or FGDA_DATA, else this checkout's build (site/dist/data.json)
4+
* when there is one, else the published copy.
5+
*/
6+
import fs from "node:fs";
7+
import path from "node:path";
8+
import { fileURLToPath } from "node:url";
9+
import { DATA_URL } from "../lib/catalog-query.mjs";
10+
11+
const LOCAL = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..", "dist", "data.json");
12+
13+
export async function loadData(source = process.env.FGDA_DATA) {
14+
const from = source || (fs.existsSync(LOCAL) ? LOCAL : DATA_URL);
15+
if (/^https:\/\//.test(from)) {
16+
const res = await fetch(from, { headers: { "user-agent": "free-game-dev-assets-cli" }, signal: AbortSignal.timeout(30000) });
17+
if (!res.ok) throw new Error(`could not load ${from}: HTTP ${res.status}`);
18+
return res.json();
19+
}
20+
return JSON.parse(fs.readFileSync(from, "utf8"));
21+
}

‎site/cli/fgda.mjs‎

Lines changed: 87 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,87 @@
1+
#!/usr/bin/env node
2+
/**
3+
* Query the catalog from a shell or CI job (#115). Zero dependencies.
4+
* fgda search [words] [--license cc0] [--category audio] [--commercial] [--no-attribution]
5+
* [--engine godot] [--format ttf] [--limit 20] [--json]
6+
* fgda get <id> [--json]
7+
* fgda check <id> [--engine unreal] [--non-commercial] [--json] exit 1 when it does not fit
8+
* fgda stacks [--json]
9+
* Every command takes --data <file|https URL> (default: this checkout's
10+
* build, else the published data.json). From anywhere:
11+
* npx github:TMHSDigital/Free-Game-Dev-Assets search "pixel font" --license cc0
12+
*/
13+
import path from "node:path";
14+
import { fileURLToPath } from "node:url";
15+
import { parseArgs } from "node:util";
16+
import { checkLicense, getAsset, listStacks, searchAssets } from "../lib/catalog-query.mjs";
17+
import { loadData } from "./data.mjs";
18+
19+
const USAGE = `usage: fgda search [words] [--license L] [--category C] [--commercial] [--no-attribution] [--engine E] [--format F] [--limit N]
20+
fgda get <id>
21+
fgda check <id> [--engine E] [--non-commercial]
22+
fgda stacks
23+
options: --data <file|https URL> --json`;
24+
25+
const line = (a) =>
26+
`${a.id} ${a.name}\n ${a.license}${a.commercial === true ? ", commercial OK" : a.commercial === "varies" ? ", per-file" : a.commercial === false ? ", NOT commercial" : ", commercial ?"}${a.attribution_required === true ? ", credit required" : a.attribution_required === false ? ", no credit" : ""}${a.engine_lock ? `, ${a.engine_lock} only` : ""}; ${a.status}; read ${a.verified || "never"}\n ${a.page}`;
27+
28+
export async function main(argv = process.argv.slice(2), out = (s) => process.stdout.write(`${s}\n`)) {
29+
const { values: o, positionals } = parseArgs({
30+
args: argv,
31+
allowPositionals: true,
32+
strict: true,
33+
options: {
34+
data: { type: "string" },
35+
json: { type: "boolean" },
36+
license: { type: "string" },
37+
category: { type: "string" },
38+
commercial: { type: "boolean" },
39+
"no-attribution": { type: "boolean" },
40+
"non-commercial": { type: "boolean" },
41+
engine: { type: "string" },
42+
format: { type: "string" },
43+
limit: { type: "string" },
44+
help: { type: "boolean", short: "h" },
45+
},
46+
});
47+
const [cmd, ...rest] = positionals;
48+
if (o.help || !cmd) {
49+
out(USAGE);
50+
return o.help ? 0 : 2;
51+
}
52+
const data = await loadData(o.data);
53+
const print = (value, text) => out(o.json ? JSON.stringify(value, null, 2) : text);
54+
if (cmd === "search") {
55+
const hits = searchAssets(data, { q: rest.join(" "), license: o.license, category: o.category, commercial: o.commercial, noAttribution: o["no-attribution"], engine: o.engine, format: o.format, limit: o.limit ? Number(o.limit) : 20 });
56+
print(hits, hits.length ? hits.map(line).join("\n\n") : "No match.");
57+
return 0;
58+
}
59+
if (cmd === "get") {
60+
const a = getAsset(data, rest[0]);
61+
if (!a) {
62+
out(`No entry "${rest[0]}".`);
63+
return 1;
64+
}
65+
print(a, line(a));
66+
return 0;
67+
}
68+
if (cmd === "check") {
69+
const r = checkLicense(data, rest[0], { commercial: !o["non-commercial"], engine: o.engine });
70+
print(r, `${r.ok ? "OK" : "CHECK"}: ${rest[0]}${r.problems.length ? `\n - ${r.problems.join("\n - ")}` : ""}${r.owes.length ? `\n owes: ${r.owes.join("; ")}` : ""}`);
71+
return r.ok ? 0 : 1;
72+
}
73+
if (cmd === "stacks") {
74+
const s = listStacks(data);
75+
print(s, s.map((x) => `${x.id} ${x.title}\n ${x.page}`).join("\n"));
76+
return 0;
77+
}
78+
out(USAGE);
79+
return 2;
80+
}
81+
82+
if (process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
83+
main().then((code) => process.exit(code), (err) => {
84+
console.error(err.message);
85+
process.exit(2);
86+
});
87+
}

‎site/cli/mcp.mjs‎

Lines changed: 111 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,111 @@
1+
#!/usr/bin/env node
2+
/**
3+
* A Model Context Protocol server over the catalog (#115), on stdio, with
4+
* no dependencies: newline-delimited JSON-RPC 2.0, the tools capability
5+
* only. Tools: search_assets, get_asset, check_license, list_stacks.
6+
* node site/cli/mcp.mjs [--data <file|https URL>]
7+
* Client config (Claude Desktop, Cursor and others):
8+
* { "command": "node", "args": ["/path/to/Free-Game-Dev-Assets/site/cli/mcp.mjs"] }
9+
*/
10+
import path from "node:path";
11+
import readline from "node:readline";
12+
import { fileURLToPath } from "node:url";
13+
import { checkLicense, getAsset, listStacks, searchAssets } from "../lib/catalog-query.mjs";
14+
import { loadData } from "./data.mjs";
15+
16+
export const TOOLS = [
17+
{
18+
name: "search_assets",
19+
description: "Search the Free Game Dev Assets catalog of free game assets and tools. Every licence was read at its source; results carry the licence, whether commercial use is OK, the credit owed and the date the licence was last checked.",
20+
inputSchema: {
21+
type: "object",
22+
properties: {
23+
query: { type: "string", description: "Words to search for, e.g. \"pixel font\"" },
24+
category: { type: "string", description: "3d, 2d, audio, characters, environment, fonts, shaders-vfx, animation, video or tools" },
25+
license: { type: "string", description: "A licence value (CC0, CC-BY-4.0, MIT...), SPDX id, or licence family" },
26+
commercial: { type: "boolean", description: "Only sources usable in a commercial game (including per-file ones)" },
27+
no_attribution: { type: "boolean", description: "Only sources that need no credit line" },
28+
engine: { type: "string", description: "godot, unity or unreal: hide sources made only for other engines" },
29+
format: { type: "string", description: "A file format, e.g. glb, png, ttf" },
30+
limit: { type: "integer", minimum: 1, maximum: 100 },
31+
},
32+
},
33+
},
34+
{
35+
name: "get_asset",
36+
description: "One catalog entry by id: licence, commercial use, credit line, status, verified date and page.",
37+
inputSchema: { type: "object", properties: { id: { type: "string" } }, required: ["id"] },
38+
},
39+
{
40+
name: "check_license",
41+
description: "Whether a catalog entry fits a use: commercial or not, and the engine it ships in. Returns problems to resolve and what it owes.",
42+
inputSchema: {
43+
type: "object",
44+
properties: { id: { type: "string" }, commercial: { type: "boolean", default: true }, engine: { type: "string" } },
45+
required: ["id"],
46+
},
47+
},
48+
{ name: "list_stacks", description: "The starter stacks: one pick per need for a kind of game.", inputSchema: { type: "object", properties: {} } },
49+
];
50+
51+
/** One tool call's result as MCP content. */
52+
export function callTool(data, name, args = {}) {
53+
const text = (v) => ({ content: [{ type: "text", text: JSON.stringify(v, null, 2) }] });
54+
if (name === "search_assets") {
55+
return text(searchAssets(data, { q: args.query || "", category: args.category, license: args.license, commercial: args.commercial, noAttribution: args.no_attribution, engine: args.engine, format: args.format, limit: args.limit }));
56+
}
57+
if (name === "get_asset") {
58+
const a = getAsset(data, args.id);
59+
return a ? text(a) : { content: [{ type: "text", text: `No entry "${args.id}".` }], isError: true };
60+
}
61+
if (name === "check_license") return text(checkLicense(data, args.id, { commercial: args.commercial !== false, engine: args.engine }));
62+
if (name === "list_stacks") return text(listStacks(data));
63+
return { content: [{ type: "text", text: `Unknown tool ${name}` }], isError: true };
64+
}
65+
66+
/** The answer to one JSON-RPC message, or null for a notification. */
67+
export function handle(msg, data) {
68+
if (msg.id === undefined || msg.id === null) return null;
69+
const reply = (result) => ({ jsonrpc: "2.0", id: msg.id, result });
70+
switch (msg.method) {
71+
case "initialize":
72+
return reply({
73+
protocolVersion: msg.params?.protocolVersion || "2025-06-18",
74+
capabilities: { tools: {} },
75+
serverInfo: { name: "free-game-dev-assets", version: String(data.version || "0") },
76+
});
77+
case "ping":
78+
return reply({});
79+
case "tools/list":
80+
return reply({ tools: TOOLS });
81+
case "tools/call":
82+
return reply(callTool(data, msg.params?.name, msg.params?.arguments || {}));
83+
default:
84+
return { jsonrpc: "2.0", id: msg.id, error: { code: -32601, message: `Method not found: ${msg.method}` } };
85+
}
86+
}
87+
88+
async function main() {
89+
const i = process.argv.indexOf("--data");
90+
const data = await loadData(i === -1 ? undefined : process.argv[i + 1]);
91+
const rl = readline.createInterface({ input: process.stdin });
92+
rl.on("line", (raw) => {
93+
if (!raw.trim()) return;
94+
let msg;
95+
try {
96+
msg = JSON.parse(raw);
97+
} catch {
98+
process.stdout.write(`${JSON.stringify({ jsonrpc: "2.0", id: null, error: { code: -32700, message: "Parse error" } })}\n`);
99+
return;
100+
}
101+
const answer = handle(msg, data);
102+
if (answer) process.stdout.write(`${JSON.stringify(answer)}\n`);
103+
});
104+
}
105+
106+
if (process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
107+
main().catch((err) => {
108+
console.error(err.message);
109+
process.exit(1);
110+
});
111+
}

‎site/lib/catalog-query.mjs‎

Lines changed: 92 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,92 @@
1+
/**
2+
* Queries over data.json for scripts and assistants (#115): the CLI
3+
* (site/cli/fgda.mjs) and the MCP server (site/cli/mcp.mjs) are thin
4+
* wrappers over these. Pure; the same search and filter code as the site.
5+
*/
6+
import { ENGINES, queryTests, scoreFields, searchFields, SORTS, worksInEngine } from "./search.mjs";
7+
import { isListed } from "./shared.mjs";
8+
9+
/** The fields an answer carries: enough to decide, with the page to read. */
10+
export function assetSummary(e, siteUrl = "") {
11+
const base = String(siteUrl).replace(/\/+$/, "");
12+
return {
13+
id: e.id,
14+
name: e.name,
15+
category: e.category,
16+
license: e.license,
17+
...(e.license_spdx ? { license_spdx: e.license_spdx } : {}),
18+
commercial: e.commercial,
19+
attribution_required: e.attribution_required,
20+
...(e.attribution_string ? { attribution_string: e.attribution_string } : {}),
21+
...(e.engine_lock ? { engine_lock: e.engine_lock } : {}),
22+
...(e.limits ? { limits: e.limits } : {}),
23+
status: e.status,
24+
...(e.review ? { open_question: e.review } : {}),
25+
verified: e.verified,
26+
url: e.url,
27+
page: base ? `${base}/${e.page}` : e.page,
28+
};
29+
}
30+
31+
/**
32+
* Listed entries matching the words and filters, best first:
33+
* { q, category, license (a licence value or family), commercial (true:
34+
* commercial OK or per-file), noAttribution, engine, format, limit }.
35+
*/
36+
export function searchAssets(data, { q = "", category, license, commercial, noAttribution, engine, format, limit = 20 } = {}) {
37+
const tests = queryTests(q);
38+
const lic = license ? String(license).toLowerCase() : null;
39+
const fmt = format ? String(format).toLowerCase() : null;
40+
const hits = [];
41+
for (const e of data.entries || []) {
42+
if (!isListed(e)) continue;
43+
if (category && e.category !== category) continue;
44+
if (lic && String(e.license).toLowerCase() !== lic && String(e.licenseFamily).toLowerCase() !== lic && String(e.license_spdx || "").toLowerCase() !== lic) continue;
45+
if (commercial && e.commercial !== true && e.commercial !== "varies") continue;
46+
if (noAttribution && e.attribution_required !== false) continue;
47+
if (engine && !worksInEngine(e, engine)) continue;
48+
if (fmt && !(e.formats || []).some((f) => String(f).toLowerCase() === fmt)) continue;
49+
const score = scoreFields(searchFields(e), tests);
50+
if (score) hits.push({ e, score });
51+
}
52+
hits.sort((a, b) => b.score - a.score || SORTS.name(a.e, b.e));
53+
return hits.slice(0, Math.max(1, Number(limit) || 20)).map((h) => assetSummary(h.e, data.site?.siteUrl));
54+
}
55+
56+
/** One entry by id, or null. */
57+
export function getAsset(data, id) {
58+
const e = (data.entries || []).find((x) => x.id === id);
59+
return e ? assetSummary(e, data.site?.siteUrl) : null;
60+
}
61+
62+
/**
63+
* Whether an entry fits a use: { ok, problems, owes }. `commercial: true`
64+
* asks for a commercial game; `engine` names the engine it ships in.
65+
* `owes` is the credit line or the notice to keep; `problems` are reasons
66+
* not to rely on it without reading the source.
67+
*/
68+
export function checkLicense(data, id, { commercial = true, engine } = {}) {
69+
const e = (data.entries || []).find((x) => x.id === id);
70+
if (!e) return { ok: false, problems: [`no entry "${id}" in the catalog`], owes: [] };
71+
const problems = [];
72+
if (commercial && e.commercial === false) problems.push("not for commercial use");
73+
if (commercial && e.commercial === "unknown") problems.push("commercial use is not established");
74+
if (e.commercial === "varies") problems.push("terms vary per file: check each file you take");
75+
if (engine && ENGINES[engine] && !worksInEngine(e, engine)) problems.push(e.engine_lock ? `licensed for ${e.engine_lock} only` : `made for another engine than ${engine}`);
76+
if (e.status === "deprecated") problems.push("deprecated in the catalog");
77+
if (e.status === "needs-review") problems.push(`needs review${e.review ? `: ${e.review}` : ""}`);
78+
if (e.attribution_required === "unknown") problems.push("the credit requirement is not established");
79+
const owes = [];
80+
if (e.attribution_required === true) owes.push(e.attribution_string ? `credit: ${e.attribution_string}` : "a credit line (see the entry)");
81+
if (e.attributionClass === "notice") owes.push("keep the licence and copyright notice with the files");
82+
return { ok: problems.length === 0, problems, owes, asset: assetSummary(e, data.site?.siteUrl) };
83+
}
84+
85+
/** The starter stacks: id, title and page. */
86+
export function listStacks(data) {
87+
const base = String(data.site?.siteUrl || "").replace(/\/+$/, "");
88+
return (data.stacks || []).map((s) => ({ id: s.id, title: s.title, page: `${base}/stack/${s.id}/` }));
89+
}
90+
91+
/** The published data.json, unless a local file or URL is given. */
92+
export const DATA_URL = "https://tmhsdigital.github.io/Free-Game-Dev-Assets/data.json";

0 commit comments

Comments
 (0)