agent-rag-mcp 0.1.0 → 0.2.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/README.md CHANGED
@@ -23,6 +23,7 @@ The `rag` commands available today are:
23
23
  - `rag import <dir>` — Ingests files from a directory.
24
24
  - `rag ls` — Lists active documents in the selected namespace.
25
25
  - `rag rm <document-id>` — Logically retires a document and preserves its history.
26
+ - `rag relabel <document-id> --label <text>` — Replaces one document's stored label.
26
27
  - `rag entity rename <from> <to>` — Corrects an entity key within the project.
27
28
  - `rag review list` — Lists version pairs awaiting a human decision.
28
29
  - `rag review link <from> <to> --type <conflicts_with|same_entity>` — Records a human link between versions with a note.
@@ -32,9 +33,11 @@ The `rag` commands available today are:
32
33
  - `rag restore --from <dir>` — Restores a backup under this root.
33
34
  - `rag reindex` — Rebuilds the database from the manifest and objects.
34
35
 
36
+ Structured files can use `.yaml`, `.yml`, `.json`, or `.jsonl`; each structured file yields one section per top-level key.
37
+
35
38
  The default knowledge-base root is `%USERPROFILE%\.rag\`. Each client has its own `rag.db` under `.rag\clients\<client>\`; projects are logical within that client and are identified by `project_id`. The namespace is the pair `(client, project)`. By default, `failClosed` is `true`; without a namespace, reads are allowed, and when `failClosed` is set to `false`, writes go to the reserved `default/default` namespace. The Tier 3 human review queue is available through `rag review list`.
36
39
 
37
- `rag add` is idempotent by `sha256`: adding the same bytes again returns the `{namespace, result}` envelope with `result.status` set to `"unchanged"` and creates no new version. A different hash creates a new `doc_version` without deleting the previous one. Deletion is a logical tombstone; version history is preserved.
40
+ `rag add` is idempotent by `sha256`: adding the same bytes again returns the `{namespace, result}` envelope with `result.status` set to `"unchanged"` and creates no new version. A different hash creates a new `doc_version` without deleting the previous one. Deletion is a logical tombstone; version history is preserved. `label` is what re-ingestion matches on, so relabeling detaches the document from future imports of that same source path, which will then appear as a new document.
38
41
 
39
42
  ## MCP
40
43
 
@@ -3,6 +3,7 @@ import { docxExtractor } from "./docx.mjs";
3
3
  import { imageOcrExtractor } from "./image-ocr.mjs";
4
4
  import { pdfExtractor } from "./pdf.mjs";
5
5
  import { plainTextExtractor } from "./plain-text.mjs";
6
+ import { jsonExtractor, jsonlExtractor, yamlExtractor } from "./structured-text.mjs";
6
7
  import { pptxExtractor } from "./pptx.mjs";
7
8
  import { xlsxExtractor } from "./xlsx.mjs";
8
9
  class UnsupportedMediaTypeError extends Error {
@@ -24,7 +25,11 @@ const extractorsByExtension = /* @__PURE__ */ new Map([
24
25
  [".xlsx", xlsxExtractor],
25
26
  [".pptx", pptxExtractor],
26
27
  [".txt", plainTextExtractor],
27
- [".md", plainTextExtractor]
28
+ [".md", plainTextExtractor],
29
+ [".yaml", yamlExtractor],
30
+ [".yml", yamlExtractor],
31
+ [".json", jsonExtractor],
32
+ [".jsonl", jsonlExtractor]
28
33
  ]);
29
34
  function getExtractorForPath(filePath) {
30
35
  const extension = path.extname(filePath).toLowerCase();
@@ -0,0 +1,150 @@
1
+ class StructuredTextExtractionError extends Error {
2
+ code;
3
+ constructor(code) {
4
+ super(code === "extraction_invalid_json" ? "Structured JSON is invalid." : "Structured YAML is invalid.");
5
+ this.name = "StructuredTextExtractionError";
6
+ this.code = code;
7
+ }
8
+ }
9
+ function getReferenceField(ref, names) {
10
+ if (typeof ref === "string") return ref;
11
+ if (typeof ref !== "object" || ref === null) return null;
12
+ const value = ref;
13
+ for (const name of names) {
14
+ if (typeof value[name] === "string") return value[name];
15
+ }
16
+ return null;
17
+ }
18
+ function supportsReference(ref, options) {
19
+ if (typeof ref !== "string") {
20
+ const mediaType = getReferenceField(ref, ["mediaType", "mimeType", "contentType"]);
21
+ if (mediaType !== null) {
22
+ return options.mediaTypes.includes(mediaType.split(";")[0].trim().toLowerCase());
23
+ }
24
+ }
25
+ const fileName = typeof ref === "string" ? ref : getReferenceField(ref, ["filename", "name", "path", "extension"]);
26
+ if (fileName === null) return false;
27
+ const normalizedFileName = fileName.toLowerCase();
28
+ return options.extensions.some((extension) => normalizedFileName.endsWith(extension));
29
+ }
30
+ function renderJsonValue(value) {
31
+ if (typeof value === "string") return value;
32
+ return JSON.stringify(value, null, 2) ?? "null";
33
+ }
34
+ function extractJson(content) {
35
+ let parsed;
36
+ try {
37
+ parsed = JSON.parse(content);
38
+ } catch {
39
+ throw new StructuredTextExtractionError("extraction_invalid_json");
40
+ }
41
+ if (typeof parsed === "object" && parsed !== null && !Array.isArray(parsed)) {
42
+ return Object.entries(parsed).map(([heading, value], ordinal) => ({
43
+ ordinal,
44
+ heading,
45
+ level: 1,
46
+ text: renderJsonValue(value)
47
+ }));
48
+ }
49
+ return [{ ordinal: 0, heading: null, level: null, text: renderJsonValue(parsed) }];
50
+ }
51
+ function extractJsonl(content) {
52
+ const sections = [];
53
+ for (const line of content.split(/\r?\n/)) {
54
+ const text = line.trim();
55
+ if (text.length === 0) continue;
56
+ try {
57
+ JSON.parse(text);
58
+ } catch {
59
+ throw new StructuredTextExtractionError("extraction_invalid_json");
60
+ }
61
+ sections.push({ ordinal: sections.length, heading: null, level: null, text });
62
+ }
63
+ return sections;
64
+ }
65
+ function extractYaml(content) {
66
+ const lines = content.split("\n").map((line) => line.replace(/\r$/, ""));
67
+ const topLevelKey = /^([A-Za-z0-9_.-]+):/;
68
+ const starts = [];
69
+ for (let index = 0; index < lines.length; index += 1) {
70
+ const line = lines[index];
71
+ if (line === void 0) continue;
72
+ if (/^[ \t]*\t/.test(line)) throw new StructuredTextExtractionError("extraction_invalid_yaml");
73
+ const match = topLevelKey.exec(line);
74
+ if (match?.[1] !== void 0) starts.push({ index, heading: match[1] });
75
+ }
76
+ if (starts.length === 0) {
77
+ return [{ ordinal: 0, heading: null, level: null, text: content }];
78
+ }
79
+ let hasCurrentBlock = false;
80
+ for (const line of lines) {
81
+ const trimmed = line.trim();
82
+ if (trimmed.length === 0 || trimmed.startsWith("#") || trimmed === "---" || trimmed === "...") continue;
83
+ const match = topLevelKey.exec(line);
84
+ if (match?.[1] !== void 0) {
85
+ hasCurrentBlock = true;
86
+ continue;
87
+ }
88
+ const indentation = line.match(/^ */)?.[0].length ?? 0;
89
+ if (indentation === 0 || !hasCurrentBlock) throw new StructuredTextExtractionError("extraction_invalid_yaml");
90
+ }
91
+ return starts.map((start, ordinal) => {
92
+ const nextStart = starts[ordinal + 1];
93
+ const block = lines.slice(start.index, nextStart?.index ?? lines.length).join("\n").trim();
94
+ return { ordinal, heading: start.heading, level: 1, text: block };
95
+ });
96
+ }
97
+ function createStructuredTextExtractor(options) {
98
+ return {
99
+ name: options.name,
100
+ version: "1.0.0",
101
+ mediaTypes: options.mediaTypes,
102
+ supports(ref) {
103
+ return supportsReference(ref, options);
104
+ },
105
+ async extract(bytes) {
106
+ const decoded = new TextDecoder("utf-8", { fatal: false, ignoreBOM: true }).decode(bytes);
107
+ const content = decoded.startsWith("\uFEFF") ? decoded.slice(1) : decoded;
108
+ if (content.length === 0) {
109
+ return { sections: [], versionLabel: null, mediaType: null };
110
+ }
111
+ let sections;
112
+ switch (options.kind) {
113
+ case "json":
114
+ sections = extractJson(content);
115
+ break;
116
+ case "jsonl":
117
+ sections = extractJsonl(content);
118
+ break;
119
+ case "yaml":
120
+ sections = extractYaml(content);
121
+ break;
122
+ }
123
+ return { sections, versionLabel: null, mediaType: options.mediaTypes[0] ?? null };
124
+ }
125
+ };
126
+ }
127
+ const jsonExtractor = createStructuredTextExtractor({
128
+ kind: "json",
129
+ name: "json",
130
+ extensions: [".json"],
131
+ mediaTypes: ["application/json"]
132
+ });
133
+ const jsonlExtractor = createStructuredTextExtractor({
134
+ kind: "jsonl",
135
+ name: "jsonl",
136
+ extensions: [".jsonl"],
137
+ mediaTypes: ["application/x-ndjson"]
138
+ });
139
+ const yamlExtractor = createStructuredTextExtractor({
140
+ kind: "yaml",
141
+ name: "yaml",
142
+ extensions: [".yaml", ".yml"],
143
+ mediaTypes: ["application/yaml"]
144
+ });
145
+ export {
146
+ StructuredTextExtractionError,
147
+ jsonExtractor,
148
+ jsonlExtractor,
149
+ yamlExtractor
150
+ };
@@ -14,6 +14,7 @@ import { getActiveLimits } from "../limits.mjs";
14
14
  import {
15
15
  linkReviewVersions,
16
16
  listReviewCandidates,
17
+ relabelDocument,
17
18
  renameEntity,
18
19
  retireDocument
19
20
  } from "../store/lifecycle.mjs";
@@ -25,6 +26,7 @@ Commands:
25
26
  import <dir> Ingest files from a directory
26
27
  ls List current documents
27
28
  rm <document-id> Retire a document without deleting its history
29
+ relabel <document-id> --label <text> Repair a document label
28
30
  entity rename <from> <to> Correct an entity key within the project
29
31
  review list List human review candidates
30
32
  review link <from> <to> --type <conflicts_with|same_entity>
@@ -42,6 +44,7 @@ Options:
42
44
  --to <dir> Backup destination
43
45
  --from <dir> Backup source
44
46
  --type <type> Human relation type for rag review link
47
+ --label <text> Replacement label for rag relabel
45
48
  --help Show this help`;
46
49
  const NAMED_ERROR_CODES = /* @__PURE__ */ new Set([
47
50
  "usage",
@@ -87,8 +90,10 @@ const NAMED_ERROR_CODES = /* @__PURE__ */ new Set([
87
90
  "entity_key_conflict",
88
91
  "project_not_found",
89
92
  "doc_version_not_found",
90
- "invalid_relation"
93
+ "invalid_relation",
94
+ "invalid_label"
91
95
  ]);
96
+ const USAGE_ERROR_CODES = /* @__PURE__ */ new Set(["usage", "invalid_label"]);
92
97
  function stripErrorPrefix(message) {
93
98
  return message.replace(/^(?:(?:ENOENT|EACCES|EPERM|EBUSY):|UNIQUE constraint failed:)\s*/, "");
94
99
  }
@@ -98,14 +103,15 @@ function publicErrorMessage(error) {
98
103
  function errorOutput(namespace, error, exitCode) {
99
104
  const rawCode = error !== null && typeof error === "object" ? error.code : void 0;
100
105
  const code = error instanceof IngestError ? "ingest_failed" : rawCode && NAMED_ERROR_CODES.has(rawCode) ? rawCode : rawCode && /^E[A-Z0-9]+$/.test(rawCode) ? "io_error" : "internal_error";
106
+ const isUsageError = USAGE_ERROR_CODES.has(code);
101
107
  return {
102
- exitCode: exitCode ?? (code === "usage" ? 2 : 1),
108
+ exitCode: exitCode ?? (isUsageError ? 2 : 1),
103
109
  output: {
104
110
  namespace,
105
111
  error: {
106
112
  code,
107
113
  message: publicErrorMessage(error),
108
- ...code === "usage" ? { usage: USAGE } : {}
114
+ ...isUsageError ? { usage: USAGE } : {}
109
115
  }
110
116
  }
111
117
  };
@@ -113,8 +119,8 @@ function errorOutput(namespace, error, exitCode) {
113
119
  function commandErrorOutput(namespace, error) {
114
120
  return errorOutput(namespace, error);
115
121
  }
116
- function usageError(message) {
117
- return Object.assign(new Error(message), { code: "usage" });
122
+ function usageError(message, code = "usage") {
123
+ return Object.assign(new Error(message), { code });
118
124
  }
119
125
  function codedError(code, message) {
120
126
  return Object.assign(new Error(message), { code });
@@ -150,15 +156,17 @@ function parseArgs(argv) {
150
156
  help = true;
151
157
  continue;
152
158
  }
153
- const assignment = /^--(to|from|type)=(.*)$/.exec(argument);
159
+ const assignment = /^--(to|from|type|label)=(.*)$/.exec(argument);
154
160
  if (assignment) {
155
161
  values[assignment[1]] = assignment[2];
156
162
  continue;
157
163
  }
158
164
  if (/^--(root|client|project)=/.test(argument)) continue;
159
- if (["--to", "--from", "--type"].includes(argument)) {
165
+ if (["--to", "--from", "--type", "--label"].includes(argument)) {
160
166
  if (argv[index + 1] === void 0 || argv[index + 1].startsWith("--")) {
161
- throw usageError(`Option ${argument} requires a value.`);
167
+ const code = argument === "--label" ? "invalid_label" : "usage";
168
+ const message = argument === "--label" ? "Option --label requires a non-blank value." : `Option ${argument} requires a value.`;
169
+ throw usageError(message, code);
162
170
  }
163
171
  values[argument.slice(2)] = argv[index + 1];
164
172
  index += 1;
@@ -374,6 +382,12 @@ async function runCli(options) {
374
382
  if (parsed.values.type !== void 0 && (parsed.command !== "review" || parsed.positional[0] !== "link")) {
375
383
  return errorOutput(config.namespace, usageError('Option --type is only accepted by "rag review link".'));
376
384
  }
385
+ if (parsed.values.label !== void 0 && parsed.command !== "relabel") {
386
+ return errorOutput(config.namespace, usageError('Option --label is only accepted by "rag relabel".'));
387
+ }
388
+ if (parsed.command === "relabel" && parsed.values.label === void 0) {
389
+ return errorOutput(config.namespace, usageError("Option --label requires a non-blank value.", "invalid_label"));
390
+ }
377
391
  if (parsed.help) return { exitCode: 0, output: { namespace: config.namespace, result: USAGE } };
378
392
  if (parsed.command === "init") {
379
393
  if (parsed.positional.length !== 0) return errorOutput(config.namespace, usageError("init does not accept positional arguments."));
@@ -443,6 +457,28 @@ async function runCli(options) {
443
457
  return errorOutput(config.namespace, error);
444
458
  }
445
459
  }
460
+ if (parsed.command === "relabel") {
461
+ if (parsed.positional.length !== 1) return errorOutput(config.namespace, usageError("relabel requires exactly one document ID."));
462
+ const label = parsed.values.label;
463
+ if (label === void 0 || label.trim().length === 0) {
464
+ return errorOutput(config.namespace, usageError("Option --label requires a non-blank value.", "invalid_label"));
465
+ }
466
+ try {
467
+ const namespace = requireNamespace(config, "write");
468
+ if (!namespace) throw new NamespaceRequiredError();
469
+ const root = path.resolve(options.cwd, config.root);
470
+ const db = openDatabase(clientDbPath(root, namespace.client));
471
+ try {
472
+ const result = relabelDocument(db, projectIdForNamespace(db, namespace), parsed.positional[0], label);
473
+ await writeRootManifest(root, db);
474
+ return { exitCode: 0, output: { namespace, result } };
475
+ } finally {
476
+ db.close();
477
+ }
478
+ } catch (error) {
479
+ return commandErrorOutput(config.namespace, error);
480
+ }
481
+ }
446
482
  if (parsed.command === "rm") {
447
483
  if (parsed.positional.length !== 1) return errorOutput(config.namespace, usageError("rm requires exactly one document ID."));
448
484
  try {
@@ -1,6 +1,7 @@
1
1
  import * as fs from "node:fs/promises";
2
2
  import { performance } from "node:perf_hooks";
3
3
  import { getExtractorForPath, UnsupportedMediaTypeError } from "../adapters/registry.mjs";
4
+ import { StructuredTextExtractionError } from "../adapters/structured-text.mjs";
4
5
  import { MAX_SOURCE_FILE_BYTES } from "../limits.mjs";
5
6
  import { ResourceLimitError } from "../ports/extractor.mjs";
6
7
  const V8_ALLOCATION_CODES = /* @__PURE__ */ new Set([
@@ -62,6 +63,10 @@ async function parse(request) {
62
63
  send({ type: "failure", requestId: request.requestId, code: error.code }, true);
63
64
  return;
64
65
  }
66
+ if (error instanceof StructuredTextExtractionError) {
67
+ send({ type: "failure", requestId: request.requestId, code: error.code }, true);
68
+ return;
69
+ }
65
70
  send({ type: "failure", requestId: request.requestId, code: classifyParseError(error) }, true);
66
71
  }
67
72
  }
@@ -16,6 +16,8 @@ const PARSE_ERROR_MESSAGES = {
16
16
  parse_invalid_result: "Document parsing returned an invalid result.",
17
17
  unsupported_media_type: "Document media type is not supported.",
18
18
  invalid_media_hint: "Document media hint is invalid.",
19
+ extraction_invalid_json: "Structured JSON is invalid.",
20
+ extraction_invalid_yaml: "Structured YAML is invalid.",
19
21
  source_too_large: "Source document exceeds the maximum supported size.",
20
22
  too_many_pages: "Document contains more pages than allowed.",
21
23
  archive_too_large: "Document archive exceeds the maximum supported size.",
@@ -43,6 +45,8 @@ const CHILD_FAILURE_CODES = /* @__PURE__ */ new Set([
43
45
  "parse_resource_exhausted",
44
46
  "unsupported_media_type",
45
47
  "invalid_media_hint",
48
+ "extraction_invalid_json",
49
+ "extraction_invalid_yaml",
46
50
  ...RESOURCE_LIMIT_CODES
47
51
  ]);
48
52
  const CHILD_DRAIN_GRACE_MS = 100;
@@ -1,6 +1,7 @@
1
1
  import { createHash, randomUUID } from "node:crypto";
2
2
  import * as path from "node:path";
3
3
  import { UnsupportedMediaTypeError } from "../adapters/registry.mjs";
4
+ import { StructuredTextExtractionError } from "../adapters/structured-text.mjs";
4
5
  import { ResourceLimitError } from "../ports/extractor.mjs";
5
6
  import { clientDbPath, openDatabase } from "../store/db.mjs";
6
7
  import { writeRootManifest } from "../store/backup.mjs";
@@ -75,9 +76,9 @@ async function ingestFile(input) {
75
76
  }
76
77
  } catch (error) {
77
78
  const detail = errorMessage(error);
78
- const resultCode = error instanceof UnsupportedMediaTypeError || error instanceof ResourceLimitError ? error.code : error instanceof ParseHostError ? error.code : "ingest_failed";
79
+ const resultCode = error instanceof UnsupportedMediaTypeError || error instanceof ResourceLimitError || error instanceof StructuredTextExtractionError ? error.code : error instanceof ParseHostError ? error.code : "ingest_failed";
79
80
  recordFailedRun(db, projectId, input.sourcePath, sha256, runStartedAt, detail, resultCode);
80
- if (error instanceof UnsupportedMediaTypeError || error instanceof ResourceLimitError || error instanceof ParseHostError) throw error;
81
+ if (error instanceof UnsupportedMediaTypeError || error instanceof ResourceLimitError || error instanceof StructuredTextExtractionError || error instanceof ParseHostError) throw error;
81
82
  throw new IngestError(detail, error);
82
83
  }
83
84
  if (extracted.sections.length === 0) {
@@ -19,6 +19,20 @@ function retireDocument(db, projectId, documentId) {
19
19
  }
20
20
  return { documentId, status: updated.deleted_at === deletedAt ? "retired" : "already_retired", deletedAt: updated.deleted_at };
21
21
  }
22
+ function relabelDocument(db, projectId, documentId, label) {
23
+ db.exec("BEGIN IMMEDIATE;");
24
+ try {
25
+ const update = db.prepare("UPDATE document SET label = ? WHERE document_id = ? AND project_id = ?").run(label, documentId, projectId);
26
+ if (Number(update.changes) !== 1) {
27
+ throw new LifecycleError("document_not_found", `Document not found in this project: ${documentId}.`);
28
+ }
29
+ db.exec("COMMIT;");
30
+ } catch (error) {
31
+ db.exec("ROLLBACK;");
32
+ throw error;
33
+ }
34
+ return { documentId, label, status: "relabeled" };
35
+ }
22
36
  function renameEntity(db, projectId, previousEntityKey, entityKey) {
23
37
  const entity = db.prepare("SELECT entity_id FROM entity WHERE project_id = ? AND entity_key = ?").get(projectId, previousEntityKey);
24
38
  if (!entity) throw new LifecycleError("entity_not_found", `Entity key not found in this project: ${previousEntityKey}.`);
@@ -141,6 +155,7 @@ export {
141
155
  LifecycleError,
142
156
  linkReviewVersions,
143
157
  listReviewCandidates,
158
+ relabelDocument,
144
159
  renameEntity,
145
160
  retireDocument
146
161
  };
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "agent-rag-mcp",
3
- "version": "0.1.0",
3
+ "version": "0.2.0",
4
4
  "description": "Deterministic, namespace-isolated document retrieval with a CLI and MCP server.",
5
5
  "license": "MIT",
6
6
  "repository": {
@@ -12,13 +12,25 @@
12
12
  "url": "https://github.com/Lsarmientov/agent-rag/issues"
13
13
  },
14
14
  "author": "Luis Daniel Sarmiento Valdiviezo",
15
- "keywords": ["rag", "mcp", "mcp-server", "document-retrieval", "knowledge-base"],
15
+ "keywords": [
16
+ "rag",
17
+ "mcp",
18
+ "mcp-server",
19
+ "document-retrieval",
20
+ "knowledge-base"
21
+ ],
16
22
  "type": "module",
17
23
  "bin": {
18
24
  "rag": "bin/rag.mjs",
19
25
  "agent-rag-mcp": "bin/agent-rag-mcp.mjs"
20
26
  },
21
- "files": ["bin", "dist", "extensions", "README.md", "LICENSE"],
27
+ "files": [
28
+ "bin",
29
+ "dist",
30
+ "extensions",
31
+ "README.md",
32
+ "LICENSE"
33
+ ],
22
34
  "pi": {
23
35
  "extensions": [
24
36
  "./extensions/agent-rag.ts"