groundwork-mcp 0.1.0 → 0.3.0

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.
package/NOTICE CHANGED
@@ -2,4 +2,4 @@ Groundwork
2
2
  Copyright 2026 The Groundwork Authors
3
3
 
4
4
  This product includes software developed by The Groundwork Authors
5
- (https://github.com/ganjilive/groundwork).
5
+ (https://github.com/IdeatorlabsAB/groundwork).
package/README.md CHANGED
@@ -26,7 +26,7 @@ claude mcp add groundwork -- npx -y groundwork-mcp
26
26
  Or install the plugin, which adds the MCP server and a skill that teaches Claude when to use it:
27
27
 
28
28
  ```
29
- /plugin marketplace add ganjilive/groundwork
29
+ /plugin marketplace add IdeatorlabsAB/groundwork
30
30
  /plugin install groundwork@groundwork
31
31
  ```
32
32
 
@@ -49,6 +49,7 @@ npx -p groundwork-mcp groundwork init # create groundwork/config.yml
49
49
  npx -p groundwork-mcp groundwork validate # check every item and link; exits 1 on errors
50
50
  npx -p groundwork-mcp groundwork trace REQ-0002
51
51
  npx -p groundwork-mcp groundwork list hypothesis
52
+ npx -p groundwork-mcp groundwork import --to <web app> # see "Groundwork for teams"
52
53
  ```
53
54
 
54
55
  `trace` shows the chain behind an item (from [examples/acme](examples/acme)):
@@ -81,7 +82,7 @@ jobs:
81
82
 
82
83
  ## Setup
83
84
 
84
- `groundwork/config.yml` holds your product areas, products and people (for approvals). The first write creates it if it's missing. Fill it in so agents can tag items by area and send requirements for sign-off:
85
+ `groundwork/config.yml` holds your product areas, products and people (for approvals). The first write creates it if it's missing. Fill it in so agents can tag items by area and send requirements for sign-off. Agents can also add product areas and products themselves, with `add_product_areas` and `add_products`; people are always added by hand:
85
86
 
86
87
  ```yaml
87
88
  name: Acme
@@ -107,6 +108,7 @@ The full format, every field and the rules are in [SPEC.md](SPEC.md). See [examp
107
108
  | | `add_requirements` | `send_back_requirement` |
108
109
  | | `update_item`, `link_items` | `obsolete_requirement` |
109
110
  | | `delete_item` | |
111
+ | | `add_product_areas`, `add_products` | |
110
112
 
111
113
  ## Privacy
112
114
 
@@ -114,7 +116,17 @@ Insights hold what customers said, and these files usually end up in git. Ground
114
116
 
115
117
  ## Groundwork for teams
116
118
 
117
- The Groundwork web app adds dashboards, reports, a visual evidence graph, approvals with an audit trail and Linear sync for people who don't live in a terminal. You can import a `groundwork/` folder into it. The web app is a separate, paid product; this project is and stays open source.
119
+ The Groundwork web app adds dashboards, reports, a visual evidence graph, approvals with an audit trail and Linear sync for people who don't live in a terminal. It's a separate, paid product; this project is and stays open source.
120
+
121
+ To move a project into it, create an agent token in the web app (**Settings → Connect an agent**), then:
122
+
123
+ ```sh
124
+ export GROUNDWORK_TOKEN=gw_…
125
+ npx -p groundwork-mcp groundwork import --to https://your-groundwork-app --dry-run # see what would happen
126
+ npx -p groundwork-mcp groundwork import --to https://your-groundwork-app
127
+ ```
128
+
129
+ Every item keeps its links, and its original id (`INS-0001`) is stored with it. Running the import again skips items already there (`--overwrite` replaces them). Afterwards `groundwork/config.yml` says `migrated:`, so local tools only read the files and the web app is where changes go. The command prints how to point your agent at the web app's MCP server.
118
130
 
119
131
  ## Contributing
120
132
 
package/SPEC.md CHANGED
@@ -100,6 +100,8 @@ people:
100
100
  migrated: https://… # set by the web app importer; local writes stop
101
101
  ```
102
102
 
103
+ `add_product_areas` and `add_products` append to `productAreas` and `products`. They skip entries already there (matched by label or name, ignoring case) and never rename, reorder or remove anything. Area ids are made from the label unless given. Rename or remove by editing the file.
104
+
103
105
  The person acting is `$GROUNDWORK_USER` (a person id). Otherwise it's the person whose `email` matches git's, or the only person listed. If none of those apply, it's `me`.
104
106
 
105
107
  ## Versioning
@@ -633,6 +633,18 @@ function writeConfig(root, config) {
633
633
  mkdirSync(join(root, DIR), { recursive: true });
634
634
  writeFileSync(configPath(root), CONFIG_HEADER + YAML.stringify(config, { lineWidth: 0 }));
635
635
  }
636
+ function appendToConfig(root, add) {
637
+ const file = configPath(root);
638
+ const doc = YAML.parseDocument(readFileSync(file, "utf8"));
639
+ for (const key of ["productAreas", "products"]) {
640
+ const values = add[key];
641
+ if (!values?.length) continue;
642
+ if (!YAML.isSeq(doc.get(key))) doc.set(key, doc.createNode([]));
643
+ const seq = doc.get(key);
644
+ for (const v of values) seq.add(doc.createNode(v));
645
+ }
646
+ writeFileSync(file, doc.toString({ lineWidth: 0 }));
647
+ }
636
648
  function gitEmail(root) {
637
649
  try {
638
650
  return execFileSync("git", ["config", "user.email"], { cwd: root, encoding: "utf8", stdio: ["ignore", "pipe", "ignore"] }).trim() || void 0;
@@ -887,7 +899,58 @@ function validate(loaded, config) {
887
899
  import { randomUUID } from "crypto";
888
900
  import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
889
901
  import { z as z4 } from "zod";
890
- var VERSION = true ? "0.1.0" : "0.0.0-dev";
902
+
903
+ // src/core/workspace.ts
904
+ var WorkspaceError = class extends Error {
905
+ };
906
+ var SLUG_ID = /^[a-z0-9][a-z0-9-]{0,39}$/;
907
+ function slugify(label) {
908
+ return label.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "").slice(0, 40).replace(/-+$/, "");
909
+ }
910
+ var same = (a, b) => a.trim().toLowerCase() === b.trim().toLowerCase();
911
+ function mergeAreas(existing, input) {
912
+ const list = [...existing];
913
+ const added = [];
914
+ const alreadyThere = [];
915
+ for (const raw of input) {
916
+ const label = raw.label.trim();
917
+ const given = raw.id?.trim();
918
+ const id = given ?? slugify(label);
919
+ if (!id) throw new WorkspaceError(`"${label}" has no letters or digits to make an id from. Give an id (lowercase letters, digits and dashes).`);
920
+ if (!SLUG_ID.test(id)) throw new WorkspaceError(`"${id}" isn't a valid area id: use up to 40 lowercase letters, digits and dashes, starting with a letter or digit.`);
921
+ const byLabel = list.find((a) => same(a.label, label));
922
+ if (byLabel) {
923
+ alreadyThere.push(byLabel);
924
+ continue;
925
+ }
926
+ const byId = list.find((a) => a.id === id);
927
+ if (byId) throw new WorkspaceError(`"${label}" would get the id "${id}", which "${byId.label}" already uses. Give a different id.`);
928
+ const area2 = { id, label };
929
+ list.push(area2);
930
+ added.push(area2);
931
+ }
932
+ return { list, added, alreadyThere };
933
+ }
934
+ function mergeProducts(existing, input) {
935
+ const list = [...existing];
936
+ const added = [];
937
+ const alreadyThere = [];
938
+ for (const raw of input) {
939
+ const name = raw.trim();
940
+ if (!name) throw new WorkspaceError("A product name can't be empty.");
941
+ const hit = list.find((p) => same(p, name));
942
+ if (hit) {
943
+ alreadyThere.push(hit);
944
+ continue;
945
+ }
946
+ list.push(name);
947
+ added.push(name);
948
+ }
949
+ return { list, added, alreadyThere };
950
+ }
951
+
952
+ // src/mcp/server.ts
953
+ var VERSION = true ? "0.3.0" : "0.0.0-dev";
891
954
  var { insightInput: insightInput2, hypothesisInput: hypothesisInput2, experimentInput: experimentInput2, findingInput: findingInput2, requirementInput: requirementInput2, PATCHES } = localSchemas;
892
955
  var INSTRUCTIONS = `Groundwork keeps this product's evidence and decisions as linked Markdown files in the groundwork/ folder, as a chain:
893
956
  insight -> hypothesis -> experiment -> finding -> requirement.
@@ -899,7 +962,7 @@ insight -> hypothesis -> experiment -> finding -> requirement.
899
962
  - Requirement: "stakeholder" (a need, in the stakeholder's words) or "solution" (what the product must do). Justified by findingIds, or, when decided elsewhere, by an origin (tender, regulation, contract, customer-need).
900
963
 
901
964
  How to work:
902
- 1. Call get_workspace first: it gives product areas, products and people (for approvers).
965
+ 1. Call get_workspace first: it gives product areas, products and people (for approvers). If an area or product you need is missing, add it with add_product_areas or add_products, after checking for an existing match.
903
966
  2. Before creating anything, search_items for duplicates and for evidence to link. Prefer linking to existing items over creating near-duplicates.
904
967
  3. Always link evidence: hypotheses to insights, experiments to a hypothesis, findings to experiments/hypotheses/insights, requirements to findings.
905
968
  4. Ask the user before deleting items or approving requirements, unless they already told you to.
@@ -982,7 +1045,7 @@ var Session = class {
982
1045
  const a = this.config.productAreas.find((x) => x.id === value || x.label.toLowerCase() === value.trim().toLowerCase());
983
1046
  if (!a) {
984
1047
  const known = this.config.productAreas.map((x) => x.label).join(", ") || "none defined";
985
- throw new UserError(`Unknown product area "${value}". Areas in groundwork/config.yml: ${known}. Add it there first, or leave it out.`);
1048
+ throw new UserError(`Unknown product area "${value}". Areas in groundwork/config.yml: ${known}. Add it with add_product_areas, or leave it out.`);
986
1049
  }
987
1050
  return a.id;
988
1051
  }
@@ -1034,15 +1097,39 @@ function buildServer({ root }) {
1034
1097
  return fail(e instanceof UserError ? e.message : `Groundwork couldn't read the project: ${e.message}`);
1035
1098
  }
1036
1099
  };
1037
- const write = (fn) => async (args) => {
1100
+ const refusal = (s) => {
1101
+ if (s.config.migrated) {
1102
+ return `This folder was imported into the Groundwork web app (${s.config.migrated}), which is now where changes go. Connect its MCP server instead (Groundwork \u2192 Settings \u2192 Connect an agent). These files are kept as a read-only record.`;
1103
+ }
1104
+ if (!s.canEdit()) return `${s.actor.person?.name ?? s.actor.id} is a viewer in groundwork/config.yml, so this agent can't change anything.`;
1105
+ return void 0;
1106
+ };
1107
+ const writeConfigOnly = (fn) => async (args) => {
1038
1108
  try {
1039
1109
  const s = open();
1040
- if (s.config.migrated) {
1041
- return fail(
1042
- `This folder was imported into the Groundwork web app (${s.config.migrated}), which is now where changes go. Connect its MCP server instead (Groundwork \u2192 Settings \u2192 Connect an agent). These files are kept as a read-only record.`
1043
- );
1110
+ const refused = refusal(s);
1111
+ if (refused) return fail(refused);
1112
+ const { add, result } = fn(s, args);
1113
+ if (!isInitialized(root)) {
1114
+ writeConfig(root, {
1115
+ ...s.config,
1116
+ productAreas: [...s.config.productAreas, ...add.productAreas ?? []],
1117
+ products: [...s.config.products, ...add.products ?? []]
1118
+ });
1119
+ } else if (add.productAreas?.length || add.products?.length) {
1120
+ appendToConfig(root, add);
1044
1121
  }
1045
- if (!s.canEdit()) return fail(`${s.actor.person?.name ?? s.actor.id} is a viewer in groundwork/config.yml, so this agent can't change anything.`);
1122
+ return ok({ ...result, file: "groundwork/config.yml" });
1123
+ } catch (e) {
1124
+ if (e instanceof UserError || e instanceof WorkspaceError) return fail(e.message);
1125
+ return fail(`Groundwork couldn't save that: ${e.message}`);
1126
+ }
1127
+ };
1128
+ const write = (fn) => async (args) => {
1129
+ try {
1130
+ const s = open();
1131
+ const refused = refusal(s);
1132
+ if (refused) return fail(refused);
1046
1133
  if (!isInitialized(root)) writeConfig(root, s.config);
1047
1134
  const { state, result } = fn(s, s.loaded.items, s.ctx(), args);
1048
1135
  const { items, renamed } = assignIds(s.loaded.items, state);
@@ -1222,10 +1309,11 @@ function buildServer({ root }) {
1222
1309
  s.check(state, "insight", r.insightIds, "insightIds");
1223
1310
  s.check(state, "hypothesis", r.hypothesisIds, "hypothesisIds");
1224
1311
  s.checkStakeholders(state, r.stakeholderIds);
1225
- if (r.product && s.config.products.length && !s.config.products.includes(r.product)) {
1226
- throw new UserError(`Unknown product "${r.product}". Products in groundwork/config.yml: ${s.config.products.join(", ")}.`);
1312
+ const product = r.product && s.config.products.find((p) => p.toLowerCase() === r.product.toLowerCase());
1313
+ if (r.product && s.config.products.length && !product) {
1314
+ throw new UserError(`Unknown product "${r.product}". Products in groundwork/config.yml: ${s.config.products.join(", ")}. Add it with add_products, or leave it out.`);
1227
1315
  }
1228
- const base = { ...r, productArea: s.area(r.productArea), aiGenerated: true };
1316
+ const base = { ...r, ...product ? { product } : {}, productArea: s.area(r.productArea), aiGenerated: true };
1229
1317
  if (r.findingIds.length) {
1230
1318
  derived.push(base);
1231
1319
  } else {
@@ -1245,6 +1333,37 @@ function buildServer({ root }) {
1245
1333
  return { state: next, result: { created: created.map((x) => s.summary("requirement", x)) } };
1246
1334
  })
1247
1335
  );
1336
+ server.registerTool(
1337
+ "add_product_areas",
1338
+ {
1339
+ title: "Add product areas",
1340
+ description: "Add product areas to groundwork/config.yml so items can be tagged with them. Give labels; ids are made from them unless you pass one. Areas already there are skipped. Check get_workspace first and reuse an existing area rather than adding a near-duplicate. Can't rename or remove areas: those are edits to config.yml.",
1341
+ inputSchema: {
1342
+ areas: z4.array(
1343
+ z4.object({
1344
+ label: z4.string().trim().min(1).max(100),
1345
+ id: z4.string().trim().max(40).optional().describe("Optional: lowercase letters, digits and dashes. Made from the label if left out.")
1346
+ })
1347
+ ).min(1).max(20)
1348
+ }
1349
+ },
1350
+ writeConfigOnly((s, { areas }) => {
1351
+ const { list, added, alreadyThere } = mergeAreas(s.config.productAreas, areas);
1352
+ return { add: { productAreas: added }, result: { added, alreadyThere, productAreas: list } };
1353
+ })
1354
+ );
1355
+ server.registerTool(
1356
+ "add_products",
1357
+ {
1358
+ title: "Add products",
1359
+ description: "Add products to groundwork/config.yml so requirements can name them. Products already there are skipped. Check get_workspace first and reuse an existing name rather than adding a near-duplicate.",
1360
+ inputSchema: { products: z4.array(z4.string().trim().min(1).max(100)).min(1).max(20) }
1361
+ },
1362
+ writeConfigOnly((s, { products }) => {
1363
+ const { list, added, alreadyThere } = mergeProducts(s.config.products, products);
1364
+ return { add: { products: added }, result: { added, alreadyThere, products: list } };
1365
+ })
1366
+ );
1248
1367
  server.registerTool(
1249
1368
  "update_item",
1250
1369
  {
@@ -1509,6 +1628,7 @@ export {
1509
1628
  ConfigError,
1510
1629
  readConfig,
1511
1630
  writeConfig,
1631
+ appendToConfig,
1512
1632
  resolveActor,
1513
1633
  COLLECTIONS,
1514
1634
  parseItem,
@@ -1521,4 +1641,4 @@ export {
1521
1641
  outgoing,
1522
1642
  buildServer
1523
1643
  };
1524
- //# sourceMappingURL=chunk-3W4X6WV2.js.map
1644
+ //# sourceMappingURL=chunk-3YZLRKZH.js.map