maggraph 0.4.1__tar.gz → 0.4.2__tar.gz

{maggraph-0.4.1 → maggraph-0.4.2}/Cargo.lock

@@ -839,7 +839,7 @@ checksum = "113b30b4cd05f7c06868fdb2854f66a7b9fece9a48425351cd532e810d74024f"
 
 [[package]]
 name = "maggraph"
-version = "0.4.1"
+version = "0.4.2"
 dependencies = [
  "axum",
  "chrono",
@@ -862,7 +862,7 @@ dependencies = [
 
 [[package]]
 name = "maggraph-cli"
-version = "0.4.1"
+version = "0.4.2"
 dependencies = [
  "assert_cmd",
  "axum",

{maggraph-0.4.1 → maggraph-0.4.2}/Cargo.toml

@@ -3,7 +3,7 @@ members = ["maggraph"]
 resolver = "2"
 
 [workspace.package]
-version = "0.4.1"
+version = "0.4.2"
 edition = "2021"
 license = "MIT OR Apache-2.0"
 repository = "https://github.com/AlexMercedCoder/MagGraph"

{maggraph-0.4.1 → maggraph-0.4.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: maggraph
-Version: 0.4.1
+Version: 0.4.2
 Classifier: Development Status :: 3 - Alpha
 Classifier: Intended Audience :: Developers
 Classifier: Intended Audience :: Science/Research
@@ -173,12 +173,13 @@ remote_sources = [
 ## MCP server scaffold
 
 ```bash
-maggraph scaffold --mcp --output ./mcp_server
+maggraph scaffold --mcp --output ./agent
 ```
 
-Generates a ready-to-run FastMCP server at `./mcp_server/server.py` wired to
-your graph index — expose `list_nodes`, `read_node`, `traverse`, `create_node`,
-and `delete_node` as MCP tools with one command.
+Generates a ready-to-run FastMCP server at `./agent/mcp_server/server.py` wired to
+your graph index — expose `list_nodes`, `get_node`, `traverse_graph`, `create_node`,
+`update_node`, and `delete_node` as MCP tools with one command. Add `--read-only`
+to leave out the write tools, and `--skill` to write `./agent/maggraph-skill/SKILL.md`.
 
 ---
 

{maggraph-0.4.1 → maggraph-0.4.2}/README.md

@@ -136,12 +136,13 @@ remote_sources = [
 ## MCP server scaffold
 
 ```bash
-maggraph scaffold --mcp --output ./mcp_server
+maggraph scaffold --mcp --output ./agent
 ```
 
-Generates a ready-to-run FastMCP server at `./mcp_server/server.py` wired to
-your graph index — expose `list_nodes`, `read_node`, `traverse`, `create_node`,
-and `delete_node` as MCP tools with one command.
+Generates a ready-to-run FastMCP server at `./agent/mcp_server/server.py` wired to
+your graph index — expose `list_nodes`, `get_node`, `traverse_graph`, `create_node`,
+`update_node`, and `delete_node` as MCP tools with one command. Add `--read-only`
+to leave out the write tools, and `--skill` to write `./agent/maggraph-skill/SKILL.md`.
 
 ---
 

{maggraph-0.4.1 → maggraph-0.4.2}/maggraph/__init__.py

@@ -50,4 +50,4 @@ __all__ = [
     "open_index",
 ]
 
-__version__ = "0.4.1"
+__version__ = "0.4.2"

{maggraph-0.4.1 → maggraph-0.4.2}/maggraph/src/agent/mod.rs

@@ -203,8 +203,62 @@ pub struct SkillRenderContext<'a> {
     pub maggraph_version: &'a str,
 }
 
+/// Options shared by the `SKILL.md` and MCP scaffold generators.
+#[derive(Debug, Clone, Copy, Default, PartialEq, Eq)]
+#[non_exhaustive]
+pub struct ScaffoldOptions {
+    /// Generate a read-only MCP server: omit the `create_node`, `update_node`, and
+    /// `delete_node` tools (and leave them out of the generated docs).
+    pub read_only: bool,
+}
+
+impl ScaffoldOptions {
+    /// Options for a read-only scaffold.
+    pub fn read_only() -> Self {
+        Self { read_only: true }
+    }
+}
+
+/// Default directory name, under the scaffold output directory, that holds `SKILL.md`.
+pub const SKILL_DIR_NAME: &str = "maggraph-skill";
+
+/// `requirements.txt` line for the published `maggraph` Python bindings, pinned to
+/// this crate's compatible release range (same minor for 0.x, same major after 1.0).
+pub fn maggraph_python_requirement() -> String {
+    let major: u64 = env!("CARGO_PKG_VERSION_MAJOR").parse().unwrap_or(0);
+    let minor: u64 = env!("CARGO_PKG_VERSION_MINOR").parse().unwrap_or(0);
+    if major == 0 {
+        format!(
+            "maggraph>={major}.{minor},<{major}.{next}",
+            next = minor + 1
+        )
+    } else {
+        format!("maggraph>={major}.{minor},<{next}", next = major + 1)
+    }
+}
+
+const READ_TOOLS_TABLE: &str = "| `list_nodes` | All indexed node ids |
+| `get_node` | Node metadata + body as Markdown |
+| `traverse_graph` | BFS/DFS traversal Markdown report |
+";
+
+const WRITE_TOOLS_TABLE: &str =
+    "| `create_node` | Create a new markdown node (optional write policy) |
+| `update_node` | Update node body/frontmatter |
+| `delete_node` | Remove a node from the index |
+";
+
 /// Render `SKILL.md` content from schema and context.
 pub fn render_skill_md(schema: &GraphSchema, ctx: &SkillRenderContext<'_>) -> String {
+    render_skill_md_with(schema, ctx, ScaffoldOptions::default())
+}
+
+/// Render `SKILL.md` content from schema, context, and scaffold options.
+pub fn render_skill_md_with(
+    schema: &GraphSchema,
+    ctx: &SkillRenderContext<'_>,
+    options: ScaffoldOptions,
+) -> String {
     let config_line = ctx
         .config_path
         .map(|p| format!("config: \"{}\"\n", p.display()))
@@ -340,25 +394,21 @@ Async: `read_node_async`, `traverse_async` (see `planning/PYTHON.md`).
 
 ## MCP server
 
-When `mcp_server/` exists:
+When `mcp_server/` exists in the scaffold output directory (next to this skill's
+`{skill_dir}/` directory), run from that output directory:
 
 ```bash
-pip install -r mcp_server/requirements.txt
-# Install maggraph from repo: cd python && maturin develop --release --features python-ext
+pip install -r mcp_server/requirements.txt   # fastmcp + maggraph from PyPI
 export MAGGRAPH_CONFIG="{config_display}"
 python mcp_server/server.py
 ```
 
+{server_mode}
+
 | Tool | Description |
 |------|-------------|
-| `list_nodes` | All indexed node ids |
-| `get_node` | Node metadata + body as Markdown |
-| `traverse_graph` | BFS/DFS traversal Markdown report |
-| `create_node` | Create a new markdown node (optional write policy) |
-| `update_node` | Update node body/frontmatter |
-| `delete_node` | Remove a node from the index |
-
-Regenerate when the graph schema changes: `maggraph scaffold --mcp --skill`.
+{tools_table}
+Regenerate when the graph schema changes: `maggraph scaffold --mcp --skill{read_only_flag}`.
 "#,
         version = ctx.maggraph_version,
         root = ctx.graph_root.display(),
@@ -377,9 +427,29 @@ Regenerate when the graph schema changes: `maggraph scaffold --mcp --skill`.
             .config_path
             .map(|p| p.display().to_string())
             .unwrap_or_else(|| "maggraph.toml".to_string()),
+        skill_dir = SKILL_DIR_NAME,
+        server_mode = if options.read_only {
+            "The server is **read-only**: it was generated with `--read-only`, so it exposes no create, update, or delete tools."
+        } else {
+            "The server is read-write. Regenerate with `--read-only` to omit the create, update, and delete tools."
+        },
+        tools_table = tools_table(options),
+        read_only_flag = if options.read_only {
+            " --read-only"
+        } else {
+            ""
+        },
     )
 }
 
+fn tools_table(options: ScaffoldOptions) -> String {
+    if options.read_only {
+        READ_TOOLS_TABLE.to_string()
+    } else {
+        format!("{READ_TOOLS_TABLE}{WRITE_TOOLS_TABLE}")
+    }
+}
+
 /// Context for MCP scaffold generation.
 #[derive(Debug, Clone)]
 pub struct McpScaffoldContext<'a> {
@@ -390,6 +460,15 @@ pub struct McpScaffoldContext<'a> {
 
 /// Write FastMCP server scaffold wired to the `maggraph` Python package.
 pub fn write_mcp_scaffold(dir: &Path, ctx: &McpScaffoldContext<'_>) -> Result<()> {
+    write_mcp_scaffold_with(dir, ctx, ScaffoldOptions::default())
+}
+
+/// Write FastMCP server scaffold with options (for example a read-only server).
+pub fn write_mcp_scaffold_with(
+    dir: &Path,
+    ctx: &McpScaffoldContext<'_>,
+    options: ScaffoldOptions,
+) -> Result<()> {
     fs::create_dir_all(dir).map_err(|e| io_error(format!("create {}: {e}", dir.display())))?;
 
     let schema = ctx.schema;
@@ -441,28 +520,27 @@ Generated by `maggraph scaffold --mcp`. Uses the `maggraph` Python bindings (PyO
 ## Setup
 
 ```bash
-# From the MagGraph repository root (if maggraph is not on PyPI yet):
-cd python && maturin develop --release --features python-ext
-
+# Installs fastmcp and the published maggraph bindings from PyPI.
 pip install -r mcp_server/requirements.txt
 export MAGGRAPH_CONFIG="{config}"
 python mcp_server/server.py
 ```
 
+To run against a MagGraph source checkout instead of the PyPI release, install the
+bindings from the repository's `python/` directory first
+(`pip install maturin && maturin develop --release --features python-ext`) and drop
+the `maggraph` line from `requirements.txt`.
+
 ## Tools
 
+{server_mode}
+
 | Tool | Description |
 |------|-------------|
-| `list_nodes` | List indexed node ids |
-| `get_node` | Read node Markdown (metadata + body) |
-| `traverse_graph` | BFS/DFS traversal report |
-| `create_node` | Create a new node (id, type, body) |
-| `update_node` | Update node body |
-| `delete_node` | Delete a node by id |
+{tools_table}
+See `planning/MCP.md` in the MagGraph repository for deployment (stdio, Cursor, CI).
 
-See [`planning/MCP.md`](../../planning/MCP.md) for deployment (stdio, Cursor, CI).
-
-Regenerate when the graph changes: `maggraph scaffold --mcp --skill`.
+Regenerate when the graph changes: `maggraph scaffold --mcp --skill{read_only_flag}`.
 "#,
         config = ctx.config_path.display(),
         root = ctx.graph_root.display(),
@@ -474,11 +552,28 @@ Regenerate when the graph changes: `maggraph scaffold --mcp --skill`.
         } else {
             ids_sample
         },
+        server_mode = if options.read_only {
+            "Read-only server (generated with `--read-only`): no create, update, or delete tools."
+        } else {
+            "Read-write server. Regenerate with `--read-only` to omit the create, update, and delete tools."
+        },
+        tools_table = tools_table(options),
+        read_only_flag = if options.read_only {
+            " --read-only"
+        } else {
+            ""
+        },
     );
 
-    let requirements = r#"fastmcp>=2.0
-# maggraph: install from repo - cd python && maturin develop --release --features python-ext
-"#;
+    let requirements = format!(
+        "fastmcp>=2.0
+{maggraph_req}
+# maggraph is the MagGraph Python bindings package on PyPI (https://pypi.org/project/maggraph/).
+# To use a source checkout instead, remove the line above and run, from the MagGraph
+# repository's python/ directory: maturin develop --release --features python-ext
+",
+        maggraph_req = maggraph_python_requirement(),
+    );
 
     let server_py = format!(
         r##"# MagGraph FastMCP server - wired to maggraph Python bindings.
@@ -497,6 +592,8 @@ CONFIG_PATH = os.environ.get("MAGGRAPH_CONFIG", r"{config}")
 GRAPH_ROOT = r"{root}"
 NODE_TYPES = {node_types:?}
 KNOWN_NODE_IDS = {node_ids:?}
+# True when generated with `maggraph scaffold --read-only` (write tools omitted).
+READ_ONLY = {read_only}
 
 
 @lru_cache(maxsize=1)
@@ -527,7 +624,35 @@ def traverse_graph(from_id: str, depth: int = 2, order: str = "bfs") -> str:
     idx = _index()
     result = idx.traverse(from_id, depth, order)
     return result.to_markdown(idx)
+{write_tools}
+
+if __name__ == "__main__":
+    mcp.run()
+"##,
+        config = ctx.config_path.display(),
+        root = ctx.graph_root.display(),
+        node_types = schema.node_types,
+        node_ids = schema.node_ids,
+        read_only = if options.read_only { "True" } else { "False" },
+        write_tools = if options.read_only {
+            ""
+        } else {
+            WRITE_TOOLS_PY
+        },
+    );
+
+    fs::write(dir.join("README.md"), readme)
+        .map_err(|e| io_error(format!("write README.md: {e}")))?;
+    fs::write(dir.join("requirements.txt"), requirements)
+        .map_err(|e| io_error(format!("write requirements.txt: {e}")))?;
+    fs::write(dir.join("server.py"), server_py)
+        .map_err(|e| io_error(format!("write server.py: {e}")))?;
+
+    Ok(())
+}
 
+/// FastMCP write tools appended to `server.py` unless the scaffold is read-only.
+const WRITE_TOOLS_PY: &str = r#"
 
 @mcp.tool
 def create_node(
@@ -538,41 +663,23 @@ def create_node(
 ) -> str:
     """Create a new markdown node. Requires write access (local or sync leader with lock)."""
     _index().create_node(node_id, node_type, body, links)
-    return f"created node {{node_id!r}}"
+    return f"created node {node_id!r}"
 
 
 @mcp.tool
 def update_node(node_id: str, body: str) -> str:
     """Replace a node's Markdown body (frontmatter preserved)."""
     _index().update_node(node_id, body)
-    return f"updated node {{node_id!r}}"
+    return f"updated node {node_id!r}"
 
 
 @mcp.tool
 def delete_node(node_id: str) -> str:
     """Delete a node by id."""
     _index().delete_node(node_id)
-    return f"deleted node {{node_id!r}}"
-
-
-if __name__ == "__main__":
-    mcp.run()
-"##,
-        config = ctx.config_path.display(),
-        root = ctx.graph_root.display(),
-        node_types = schema.node_types,
-        node_ids = schema.node_ids,
-    );
-
-    fs::write(dir.join("README.md"), readme)
-        .map_err(|e| io_error(format!("write README.md: {e}")))?;
-    fs::write(dir.join("requirements.txt"), requirements)
-        .map_err(|e| io_error(format!("write requirements.txt: {e}")))?;
-    fs::write(dir.join("server.py"), server_py)
-        .map_err(|e| io_error(format!("write server.py: {e}")))?;
+    return f"deleted node {node_id!r}"
 
-    Ok(())
-}
+"#;
 
 /// Write `SKILL.md` to `path`.
 pub fn write_skill_md(
@@ -580,7 +687,17 @@ pub fn write_skill_md(
     schema: &GraphSchema,
     ctx: &SkillRenderContext<'_>,
 ) -> Result<()> {
-    let content = render_skill_md(schema, ctx);
+    write_skill_md_with(path, schema, ctx, ScaffoldOptions::default())
+}
+
+/// Write `SKILL.md` to `path` using scaffold options.
+pub fn write_skill_md_with(
+    path: &Path,
+    schema: &GraphSchema,
+    ctx: &SkillRenderContext<'_>,
+    options: ScaffoldOptions,
+) -> Result<()> {
+    let content = render_skill_md_with(schema, ctx, options);
     if let Some(parent) = path.parent() {
         fs::create_dir_all(parent)
             .map_err(|e| io_error(format!("create {}: {e}", parent.display())))?;
@@ -649,5 +766,77 @@ mod tests {
         assert!(server.contains("import maggraph"));
         assert!(server.contains("def traverse_graph"));
         assert!(server.contains("def create_node"));
+        assert!(server.contains("def delete_node"));
+        assert!(server.contains("READ_ONLY = False"));
+        assert!(server.contains("return f\"created node {node_id!r}\""));
+    }
+
+    fn basic_schema() -> (PathBuf, GraphSchema) {
+        let root =
+            PathBuf::from(env!("CARGO_MANIFEST_DIR")).join("../examples/basic/knowledge_graph");
+        let index = GraphIndex::open(&root).expect("open");
+        let schema = GraphSchema::introspect(&index).expect("introspect");
+        (root, schema)
+    }
+
+    #[test]
+    fn read_only_mcp_scaffold_omits_write_tools() {
+        let (root, schema) = basic_schema();
+        let tmp = tempfile::tempdir().expect("tempdir");
+        let mcp_dir = tmp.path().join("mcp_server");
+        let ctx = McpScaffoldContext {
+            graph_root: &root,
+            config_path: Path::new("maggraph.toml"),
+            schema: &schema,
+        };
+        write_mcp_scaffold_with(&mcp_dir, &ctx, ScaffoldOptions::read_only()).expect("write");
+        let server = fs::read_to_string(mcp_dir.join("server.py")).expect("server");
+        assert!(server.contains("def traverse_graph"));
+        assert!(server.contains("READ_ONLY = True"));
+        assert!(!server.contains("create_node"));
+        assert!(!server.contains("update_node"));
+        assert!(!server.contains("delete_node"));
+        let readme = fs::read_to_string(mcp_dir.join("README.md")).expect("readme");
+        assert!(!readme.contains("`delete_node`"));
+    }
+
+    #[test]
+    fn read_only_skill_omits_write_tools() {
+        let (root, schema) = basic_schema();
+        let ctx = SkillRenderContext {
+            graph_root: &root,
+            config_path: Some(Path::new("maggraph.toml")),
+            storage_mode: Some("local"),
+            maggraph_version: "0.4.1",
+        };
+        let rw = render_skill_md(&schema, &ctx);
+        assert!(rw.contains("`create_node`"));
+        let ro = render_skill_md_with(&schema, &ctx, ScaffoldOptions::read_only());
+        assert!(ro.contains("`traverse_graph`"));
+        assert!(!ro.contains("`create_node`"));
+        assert!(ro.contains("maggraph scaffold --mcp --skill --read-only"));
+    }
+
+    #[test]
+    fn requirements_pin_published_bindings_to_compatible_range() {
+        let req = maggraph_python_requirement();
+        let major = env!("CARGO_PKG_VERSION_MAJOR");
+        let minor = env!("CARGO_PKG_VERSION_MINOR");
+        assert!(
+            req.starts_with(&format!("maggraph>={major}.{minor},<")),
+            "{req}"
+        );
+
+        let (root, schema) = basic_schema();
+        let tmp = tempfile::tempdir().expect("tempdir");
+        let ctx = McpScaffoldContext {
+            graph_root: &root,
+            config_path: Path::new("maggraph.toml"),
+            schema: &schema,
+        };
+        write_mcp_scaffold(tmp.path(), &ctx).expect("write");
+        let requirements = fs::read_to_string(tmp.path().join("requirements.txt")).expect("req");
+        assert!(requirements.lines().any(|line| line == req));
+        assert!(requirements.contains("pypi.org/project/maggraph"));
     }
 }

{maggraph-0.4.1 → maggraph-0.4.2}/maggraph/src/index.rs

@@ -36,12 +36,39 @@ impl NodeIndexEntry {
     }
 }
 
+/// File names (matched case-insensitively) that are commonly documentation rather
+/// than graph nodes. When one of these files does not parse as a node it is skipped
+/// and reported through [`GraphIndex::skipped_files`] instead of failing the scan.
+/// A file with one of these names that *is* a valid node is still indexed.
+pub const NON_NODE_FILE_NAMES: &[&str] = &["SKILL.md", "README.md", "AGENTS.md", "CLAUDE.md"];
+
+/// A markdown file under the graph root that the scan skipped because it is not a node.
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct SkippedFile {
+    /// Path relative to the graph root.
+    pub relative_path: PathBuf,
+    /// Why the file was not indexed (the node parse error).
+    pub reason: String,
+}
+
+/// Whether `path` has one of the [`NON_NODE_FILE_NAMES`].
+pub fn is_non_node_file_name(path: &Path) -> bool {
+    path.file_name()
+        .and_then(|name| name.to_str())
+        .is_some_and(|name| {
+            NON_NODE_FILE_NAMES
+                .iter()
+                .any(|reserved| reserved.eq_ignore_ascii_case(name))
+        })
+}
+
 /// In-memory index of markdown nodes under a graph root.
 #[derive(Debug, Clone, PartialEq, Eq)]
 pub struct GraphIndex {
     root_path: PathBuf,
     by_id: HashMap<String, NodeIndexEntry>,
     by_path: HashMap<PathBuf, String>,
+    skipped: Vec<SkippedFile>,
 }
 
 impl GraphIndex {
@@ -71,6 +98,7 @@ impl GraphIndex {
             root_path,
             by_id: HashMap::new(),
             by_path: HashMap::new(),
+            skipped: Vec::new(),
         };
         index.rescan()?;
         Ok(index)
@@ -80,6 +108,7 @@ impl GraphIndex {
     pub fn rescan(&mut self) -> Result<()> {
         self.by_id.clear();
         self.by_path.clear();
+        self.skipped.clear();
 
         for entry in WalkDir::new(&self.root_path)
             .follow_links(false)
@@ -111,13 +140,39 @@ impl GraphIndex {
                 continue;
             }
 
-            let node = Node::from_file(path, &self.root_path)?;
+            let node = match Node::from_file(path, &self.root_path) {
+                Ok(node) => node,
+                Err(MagGraphError::NodeParse { message, .. })
+                    if is_non_node_file_name(relative_path) =>
+                {
+                    tracing::warn!(
+                        path = %relative_path.display(),
+                        reason = %message,
+                        "skipping non-node markdown file"
+                    );
+                    self.skipped.push(SkippedFile {
+                        relative_path: relative_path.to_path_buf(),
+                        reason: message,
+                    });
+                    continue;
+                }
+                Err(err) => return Err(err),
+            };
             self.insert_entry(node.metadata, relative_path.to_path_buf(), node.body)?;
         }
 
+        self.skipped
+            .sort_by(|a, b| a.relative_path.cmp(&b.relative_path));
         Ok(())
     }
 
+    /// Markdown files the last full scan skipped because they are documentation
+    /// (see [`NON_NODE_FILE_NAMES`]) that does not parse as a node, such as a
+    /// generated `SKILL.md` or a `README.md` without node frontmatter.
+    pub fn skipped_files(&self) -> &[SkippedFile] {
+        &self.skipped
+    }
+
     pub fn root_path(&self) -> &Path {
         &self.root_path
     }
@@ -175,10 +230,28 @@ impl GraphIndex {
             if let Some(existing_id) = self.by_path.remove(&relative_path) {
                 self.by_id.remove(&existing_id);
             }
+            self.skipped.retain(|s| s.relative_path != relative_path);
             return Ok(None);
         }
 
-        let node = Node::from_file(&full_path, &self.root_path)?;
+        let node = match Node::from_file(&full_path, &self.root_path) {
+            Ok(node) => node,
+            Err(MagGraphError::NodeParse { message, .. })
+                if is_non_node_file_name(&relative_path) =>
+            {
+                if let Some(existing_id) = self.by_path.remove(&relative_path) {
+                    self.by_id.remove(&existing_id);
+                }
+                self.skipped.retain(|s| s.relative_path != relative_path);
+                self.skipped.push(SkippedFile {
+                    relative_path,
+                    reason: message,
+                });
+                return Ok(None);
+            }
+            Err(err) => return Err(err),
+        };
+        self.skipped.retain(|s| s.relative_path != relative_path);
         let id = node.id().to_string();
         if let Some(existing) = self.by_id.get(&id) {
             if existing.relative_path != relative_path {
@@ -615,6 +688,71 @@ links: ["welcome"]
         assert!(!root.join("customer_churn_q2.md").exists());
     }
 
+    #[test]
+    fn scan_skips_and_reports_documentation_files_that_are_not_nodes() {
+        let temp = TempDir::new().expect("temp dir");
+        let root = temp.path().join("graph");
+        write_example_graph(&root);
+        // A generated SKILL.md has frontmatter but no `id`; a README has none at all.
+        fs::write(
+            root.join("SKILL.md"),
+            "---\nmaggraph_skill_version: \"0.4.1\"\nnode_count: 2\n---\n\n# Skill\n",
+        )
+        .expect("write skill");
+        fs::create_dir_all(root.join("docs")).expect("docs dir");
+        fs::write(root.join("docs/readme.md"), "# Notes about this graph\n").expect("readme");
+
+        let mut index = GraphIndex::open(&root).expect("open index despite non-node files");
+        assert_eq!(index.len(), 2);
+        let skipped: Vec<_> = index
+            .skipped_files()
+            .iter()
+            .map(|s| s.relative_path.clone())
+            .collect();
+        assert_eq!(
+            skipped,
+            vec![PathBuf::from("SKILL.md"), PathBuf::from("docs/readme.md")]
+        );
+        assert!(index.skipped_files()[0].reason.contains("id"));
+
+        // Incremental refresh of a skipped file is a no-op rather than an error.
+        assert_eq!(index.update_file("SKILL.md").expect("refresh skill"), None);
+        assert_eq!(index.skipped_files().len(), 2);
+        fs::remove_file(root.join("SKILL.md")).expect("remove skill");
+        assert_eq!(
+            index.update_file("SKILL.md").expect("refresh removed"),
+            None
+        );
+        assert_eq!(index.skipped_files().len(), 1);
+    }
+
+    #[test]
+    fn readme_that_is_a_valid_node_is_still_indexed() {
+        let temp = TempDir::new().expect("temp dir");
+        let root = temp.path().join("graph");
+        write_example_graph(&root);
+        fs::write(
+            root.join("README.md"),
+            "---\nid: graph_readme\ntype: note\n---\n\n# Readme node\n",
+        )
+        .expect("write readme");
+
+        let index = GraphIndex::open(&root).expect("open index");
+        assert!(index.contains("graph_readme"));
+        assert!(index.skipped_files().is_empty());
+    }
+
+    #[test]
+    fn ordinary_malformed_node_still_fails_the_scan() {
+        let temp = TempDir::new().expect("temp dir");
+        let root = temp.path().join("graph");
+        write_example_graph(&root);
+        fs::write(root.join("broken.md"), "---\ntype: note\n---\n\nNo id\n").expect("write");
+
+        let err = GraphIndex::open(&root).expect_err("malformed node must fail");
+        assert!(matches!(err, MagGraphError::NodeParse { .. }));
+    }
+
     #[test]
     fn detects_duplicate_ids_on_scan() {
         let temp = TempDir::new().expect("temp dir");

{maggraph-0.4.1 → maggraph-0.4.2}/maggraph/src/lib.rs

@@ -18,8 +18,10 @@ pub mod ui;
 pub mod wikilink;
 
 pub use agent::{
-    render_skill_md, write_mcp_scaffold, write_skill_md, EdgePattern, EdgeSource, GraphSchema,
-    McpScaffoldContext, SchemaEdge, SkillRenderContext,
+    maggraph_python_requirement, render_skill_md, render_skill_md_with, write_mcp_scaffold,
+    write_mcp_scaffold_with, write_skill_md, write_skill_md_with, EdgePattern, EdgeSource,
+    GraphSchema, McpScaffoldContext, ScaffoldOptions, SchemaEdge, SkillRenderContext,
+    SKILL_DIR_NAME,
 };
 pub use batch::{
     apply_memory_batch, validate_memory_batch, MemoryBatchOperation, MemoryBatchResult,
@@ -32,7 +34,7 @@ pub use error::{MagGraphError, Result};
 pub use graph::{
     resolve_target, traverse, GraphAdjacency, TraversalNode, TraversalOrder, TraversalResult,
 };
-pub use index::{GraphIndex, NodeIndexEntry};
+pub use index::{GraphIndex, NodeIndexEntry, SkippedFile};
 pub use lakehouse::{
     ContentCache, ContentResolver, FileResolver, HttpResolver, LakehouseReader, NodeWithContent,
     ResolvedContent, ResolverRegistry, S3StubResolver,

{maggraph-0.4.1 → maggraph-0.4.2}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "maturin"
 
 [project]
 name = "maggraph"
-version = "0.4.1"
+version = "0.4.2"
 description = "In-process graph engine for AI semantic layers — powered by Rust"
 readme = "README.md"
 requires-python = ">=3.9"