EISDIR error when creating/adding observations for directory paths (client reads directory as a file)

[punkyard]

Summary

While creating entities or adding observations with the memory MCP server, we observed intermittent EISDIR errors when entity names corresponded to directory paths (e.g., .github). The error is triggered when a client or server attempts to read a directory as if it were a file and fails with Node's EISDIR error.

Environment

• Node: 24.x (example from workspace: v24.11.1)
• npx: 11.x
• Memory server: @modelcontextprotocol/server-memory
• Workspace: firstb00t-v2 (project-level analysis performed on: /Users/nmn/rez0/neimen/0-code/github-pun/firstb00t-v2)

Reproduction steps (simplified)

1. Stop the memory server or ensure it is unreachable.
2. From a client (or wrapper) call the memory MCP API create_entities or add_observations with an entity name that maps to an existing directory (e.g., .github) while not explicitly specifying entityType or specifying entityType incorrectly as file.
3. If the client attempts to read the path or infers the path as a file, fs.readFile will be invoked and an EISDIR error occurs: EISDIR: illegal operation on a directory, read <path>.

Observed

• Error message from Node: EISDIR: illegal operation on a directory, read <path>.
• The memory creation calls can partially succeed or fail — leading to inconsistent memory graph state.

Expected

• The MCP memory server or client should clearly handle directories and files separately.
  • For directories, either create an entity with entityType: "folder" or return a descriptive validation error asking the user to provide entityType: "folder".
  • For files, accept the request and, when specified, read file contents or add string observations without implicit filesystem reads.
• The client should not attempt to fallback to local filesystem reads when the memory server is offline; instead, return a connection error.

Potential root causes

• Client wrapper calls may attempt to read local file content automatically if a path-like name was provided (and entityType is not provided), and fs.readFile is invoked on a directory.
• Server-side may accept name as a raw string without proper validation or safe handling of directories vs. files.
• Server might accept wrong entityType values and not warning clearly.

Suggested fixes

1. Server-side validation
   • Validate the entityType upon /create_entities call and return clear, descriptive errors.
   • If entityType is not provided, return a validation error rather than attempting to infer a file read.
2. Client-side helper
   • Add a client wrapper that uses fs.stat() to check path type before any reads. If stat.isDirectory() return entityType: "folder" or raise a validation error.
   • If the server is offline, return a connection error and avoid falling back to local file reads.
3. Better logging
   • Add a more descriptive error message that indicates a directory path was provided and that a folder entity is required if that is intended.
4. Tests
   • Add unit/integration tests to validate behavior of both file & folder entityType creation, including offline server test to ensure no local file reads occur.

Attachments (from local analysis)

• .context/eisdir_analysis.md — local analysis of root cause for EISDIR error.
• .context/mem_import_2025-11-28.json — audit of entities & relations created while testing.
• .context/filetree.md — canonical file tree with clear folder/file separation.

Notes

• I can open a PR to add a client-side wrapper and tests if you want. Also happy to contribute a patch to server-side validation to make errors clearer.