32 provide installation instructions

[ndaelman-hu]

Apply a "Try Before You Buy" design, where the project gets distributed as a MCP server and dependency.
Both code shipping systems, though I managed to make it work when targeting the GitHub repo. This may become more complex when we register them at each platform.

More specifically:

• restructure folders to
  • easily find src
  • find MCP servers by usage
  • disentangle MCP layer from the underlying methods
• add installations instructions with templates for various hosts
• add import tests
• set up as GitHub CI/CD

closes #32

[ndaelman-hu]

So, this is my main proposal. Any feedback? Other options include

• splitting into 2 projects (maybe for when it's mature enough to register).
• focusing on a more documentatrion-style approach, where we explain the MCP server how to load these packages (even when it cannot introspect).

[ndaelman-hu]

I am testing the setup for myself with VS Code, and also have Claude Code planned.
Can anyone go over the new installation instructions and try them out too?
Feel free to give feedback on the text to, but pls do it as a review with code suggestions.

[Sideboard]

Installation worked fine:

git clone <repository>
cd parse-patrol
uv sync
uv sync --extra cclib

Something's wrong with the python config:

(parse-patrol) ➜  parse-patrol git:(32-provide-installation-instructions) ✗ python
Python 3.12.11 (main, Aug 18 2025, 19:19:11) [Clang 20.1.4 ] on linux
Type "help", "copyright", "credits" or "license" for more information.
Ctrl click to launch VS Code Native REPL
]633;C]633;E;None]633;D;0]633;A>>> ]633;Bimport parse_patrol
/home/klawohns/work/code/parse-patrol/.venv/lib/python3.12/site-packages/cclib/method/volume.py:16: SyntaxWarning: invalid escape sequence '\p'
  \psi (x, y, z) = x^a * y^b * z^c * exp(-\lambda * r^2)
]633;C]633;E;import parse_patrol]633;D;0]633;A>>> ]633;B

It worked better a second time, not sure why:

(parse-patrol) ➜  parse-patrol git:(32-provide-installation-instructions) ✗ python
Python 3.12.11 (main, Aug 18 2025, 19:19:11) [Clang 20.1.4 ] on linux
Type "help", "copyright", "credits" or "license" for more information.
Ctrl click to launch VS Code Native REPL
]633;C]633;E;parse_patrol.available_parsers()]633;D;0]633;A>>> ]633;Bimport parse_patrol
]633;C]633;E;import parse_patrol]633;D;0]633;A>>> ]633;Bparse_patrol.available_parsers()
['cclib', 'gaussian']
]633;C]633;E;parse_patrol.available_parsers()]633;D;0]633;A>>> ]633;B

But why is gaussian available?

---

from parse_patrol import cclib_parse  # Pylint says: No name 'cclib_parse' in module 'parse_patrol' 

result = cclib_parse(".pipelines/data/gaussian/frequency.gjf")

(parse-patrol) ➜  parse-patrol git:(32-provide-installation-instructions) ✗ python mytest.py                         
Unable to determine the type of logfile ['.pipelines/data/gaussian/frequency.gjf'], try the fallback mechanism
Traceback (most recent call last):
  File "/home/klawohns/work/code/parse-patrol/mytest.py", line 3, in <module>
    result = cclib_parse(".pipelines/data/gaussian/frequency.gjf")
             ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/home/klawohns/work/code/parse-patrol/src/parse_patrol/parsers/cclib/utils.py", line 134, in cclib_parse
    raise FileNotFoundError(f"File not found or unsupported format: {filepath}")
FileNotFoundError: File not found or unsupported format: .pipelines/data/gaussian/frequency.gjf

Do we want the traceback here?

---

(parse-patrol) ➜  parse-patrol git:(32-provide-installation-instructions) ✗ uv run mcp dev -m parse_patrol
Usage: mcp dev [OPTIONS] FILE_SPEC
Try 'mcp dev --help' for help.
╭─ Error ────────────────────────────────────────────────────────────────────────────────────────────────────────────────╮
│ No such option: -m                                                                                                     │
╰────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯

---

Using a screenshot for .vscode/mcp.json has the disadvantage that one cannot copy & paste it. We should either replace with code, or add it as well (are tabs possible in markdown?), or have a template file with exactly that content.

Oh, it's only about showing that you can run the server by clicking play. Then the image is probably helpful. But why is the configuration then after this? Don't we need the configuration before?

---

Stopping here for now.

[ndaelman-hu]

@Sideboard thank you for the feedback, they are very welcomed. It would be nicer to convert them to bulletpoints, so I can tick them off.

Something's wrong with the python config:

Has been patched now. Nothing major, just versioning effects for cclib.

But why is gaussian available?

What do you mean?

Do we want the traceback here?

Is mytest.py a test file that you produced. Who'se calling the cclib_parse on it, the agent or some code?
Regarding the file path, I do have this file, but would move any tests into tests. Let me see to add one for each parser, which downloads an upload via nomad and parses it.

Using a screenshot for [...]

One of us should open an issue for this.

[QuantumChemist]

This is a really good PR, I have left some suggestions :)

[ndaelman-hu]

@Sideboard @QuantumChemist thank you both for the feedback. I incorporated almost all of it, and documented that in my replies. I am happy to notice that there were not particular objections to the new structure itself. If you are each satisfied, could you pls sign off?

While there are still some points to polish (will open new follow-up PRs), I think that the objective of laying a new foundation has been met. I verified that it works in NOMAD, and would like to proceed with more targeted, incremental improvements.

[QuantumChemist]

crazy, you have really polished the code! I really like it that way! :O :D

[ndaelman-hu]

crazy, you have really polished the code! I really like it that way! :O :D

Haha, thank you very much! That's why it took a while. Hope this will facilitate development for everyone.