@convesoft/mara 0.1.0-alpha.0 → 0.1.0-alpha.1

package/README.md

@@ -32,14 +32,62 @@ command = "npx"
 args = ["-y", "@convesoft/mara@0.1.0-alpha.0", "mcp"]
 ```
 
-If the client starts elsewhere, add an explicit project root before `mcp`:
+To bind the server to one project regardless of its execution directory, place
+`--project` after `mcp`:
 
-```text
---project /absolute/path/to/project
+```toml
+[mcp_servers.mara]
+command = "npx"
+args = [
+  "-y",
+  "@convesoft/mara@0.1.0-alpha.0",
+  "mcp",
+  "--project",
+  "/absolute/path/to/project",
+]
+```
+
+Without `--project`, the server can start anywhere. Project-bound tools accept
+an absolute `project` path or discover the nearest parent containing
+`.mara/project.toml` from the server's execution directory.
+
+## Agent Plugin package
+
+The main npm package also contains a portable Agent Plugins 1.0 manifest, a
+Mara skill, and stdio MCP configuration. Compatible clients can install that
+package through their supported plugin distribution flow. Codex is the
+reference client; the portable package does not modify project `AGENTS.md`.
+
+Starting with `0.1.0-alpha.1`, a user without an existing Mara installation can
+install the complete package from the Convesoft Codex marketplace:
+
+```bash
+codex plugin marketplace add convesoft/mara
+codex plugin add mara@convesoft
+```
+
+Start a new Codex session after installation. Codex keeps an installed plugin
+snapshot in its managed cache. On first MCP start, its launcher uses `npx` to
+install and run that snapshot's exact Mara version with the matching native
+package in npm's cache.
+
+If Mara and its MCP server are already configured, install only the skill and
+keep using that existing executable:
+
+```bash
+npx skills add convesoft/mara --skill mara -g -a codex
+```
+
+For a new MCP registration backed by an existing installation, use the
+executable's absolute path:
+
+```bash
+codex mcp add mara -- /absolute/path/to/mara mcp
 ```
 
-Mara discovers the nearest parent containing `.mara/project.toml` and binds one
-project when the MCP server starts.
+Use either the complete plugin or the existing-installation route. Do not add
+the complete plugin alongside an equivalent manually configured Mara MCP
+server.
 
 ## Core workflow
 

package/bin/mara-plugin.cjs

@@ -0,0 +1,57 @@
+#!/usr/bin/env node
+
+"use strict";
+
+const path = require("node:path");
+const { spawn } = require("node:child_process");
+
+const packages = new Map([
+  ["linux:x64", "@convesoft/mara-linux-x64-gnu"],
+  ["linux:arm64", "@convesoft/mara-linux-arm64-gnu"],
+  ["darwin:x64", "@convesoft/mara-darwin-x64"],
+  ["darwin:arm64", "@convesoft/mara-darwin-arm64"],
+]);
+
+const manifest = require("../package.json");
+const packageName = packages.get(`${process.platform}:${process.arch}`);
+let hasLocalRuntime = false;
+
+if (packageName !== undefined) {
+  try {
+    require.resolve(`${packageName}/package.json`);
+    hasLocalRuntime = true;
+  } catch {
+    // Codex extracts npm plugin packages without installing their dependencies.
+  }
+}
+
+const command = hasLocalRuntime ? process.execPath : "npx";
+const args = hasLocalRuntime
+  ? [path.join(__dirname, "mara.cjs"), ...process.argv.slice(2)]
+  : ["--yes", `${manifest.name}@${manifest.version}`, ...process.argv.slice(2)];
+const child = spawn(command, args, { stdio: "inherit" });
+const signals = ["SIGINT", "SIGTERM", "SIGHUP"];
+const forward = new Map();
+
+for (const signal of signals) {
+  const handler = () => child.kill(signal);
+  forward.set(signal, handler);
+  process.on(signal, handler);
+}
+
+child.once("error", (error) => {
+  console.error(`Could not start Mara from the Agent Plugin: ${error.message}`);
+  process.exitCode = 1;
+});
+
+child.once("exit", (code, signal) => {
+  for (const [name, handler] of forward) {
+    process.off(name, handler);
+  }
+
+  if (signal !== null) {
+    process.kill(process.pid, signal);
+  } else {
+    process.exitCode = code ?? 1;
+  }
+});

package/mcp.json

@@ -0,0 +1,10 @@
+{
+  "$schema": "https://agent-plugins.org/schemas/1.0.0/mcp.schema.json",
+  "mcpServers": {
+    "mara": {
+      "type": "stdio",
+      "command": "node",
+      "args": ["${PLUGIN_ROOT}/bin/mara-plugin.cjs", "mcp"]
+    }
+  }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@convesoft/mara",
-  "version": "0.1.0-alpha.0",
+  "version": "0.1.0-alpha.1",
   "description": "Structured project knowledge CLI and MCP server",
   "author": "Aliaksei Raketski",
   "license": "MIT OR Apache-2.0",
@@ -18,13 +18,17 @@
     "node": ">=18"
   },
   "optionalDependencies": {
-    "@convesoft/mara-linux-x64-gnu": "0.1.0-alpha.0",
-    "@convesoft/mara-linux-arm64-gnu": "0.1.0-alpha.0",
-    "@convesoft/mara-darwin-x64": "0.1.0-alpha.0",
-    "@convesoft/mara-darwin-arm64": "0.1.0-alpha.0"
+    "@convesoft/mara-linux-x64-gnu": "0.1.0-alpha.1",
+    "@convesoft/mara-linux-arm64-gnu": "0.1.0-alpha.1",
+    "@convesoft/mara-darwin-x64": "0.1.0-alpha.1",
+    "@convesoft/mara-darwin-arm64": "0.1.0-alpha.1"
   },
   "files": [
     "bin/mara.cjs",
+    "bin/mara-plugin.cjs",
+    "plugin.json",
+    "mcp.json",
+    "skills/mara/SKILL.md",
     "README.md",
     "LICENSE-MIT",
     "LICENSE-APACHE"

package/plugin.json

@@ -0,0 +1,19 @@
+{
+  "$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json",
+  "name": "mara",
+  "description": "Discover, author, relate, and validate structured project knowledge.",
+  "author": {
+    "name": "Convesoft",
+    "url": "https://github.com/convesoft"
+  },
+  "homepage": "https://github.com/convesoft/mara",
+  "repository": "https://github.com/convesoft/mara",
+  "license": "MIT OR Apache-2.0",
+  "keywords": [
+    "project-knowledge",
+    "requirements",
+    "mcp",
+    "agent-skill"
+  ],
+  "version": "0.1.0-alpha.1"
+}

package/skills/mara/SKILL.md

@@ -0,0 +1,40 @@
+---
+name: mara
+description: Use Mara to initialize, discover, author, relate, retrieve, search, or validate structured project knowledge in Git-tracked *.mara.md files.
+---
+
+# Mara project knowledge
+
+Use the Mara MCP tools as the structured interface to a project's canonical
+`*.mara.md` knowledge.
+
+## Select the project
+
+- Resolve the intended project root to an absolute path.
+- Pass that path as `project` on every project-bound tool call unless the MCP
+  server was explicitly started with `mara mcp --project PATH`.
+- If `project` is omitted, Mara discovers the nearest project from the MCP
+  server's execution directory.
+- Treat each operation as scoped to one project. Do not infer workspace or
+  cross-project behavior.
+
+If the intended root has no `.mara/project.toml` and the user wants to start a
+Mara project, call `project_init` with the absolute root, or omit `project` when
+the MCP server was started with that root bound by `--project`. Use the default
+`minimal` template unless the user explicitly requests `empty`. Do not create
+or modify `AGENTS.md` as part of Mara onboarding.
+
+## Work with the corpus
+
+1. Call `schema_get` before authoring unfamiliar flavours, fields, or relations.
+2. Use `item_search`, `item_list`, and `item_related` for bounded discovery;
+   call `item_get` only for selected full items.
+3. Use `item_create`, `relation_add`, and `relation_remove` only when the user
+   has asked to change project knowledge.
+4. Run the narrowest relevant validation after a mutation and use
+   `project_validate` when the requested work affects corpus-wide integrity.
+
+Mara source files remain canonical. Do not treat MCP results as a separate
+authoring store. Structured update, move, rename, and delete operations are not
+available yet; when one is required, edit the source file directly and validate
+the result.