Skip to content

Commit f916428

Browse files
sbillingesbillinge
authored
Merge pull request #47 from ycexiao/agent-docs
docs: update the documentation for using Diffpy MCP
2 parents e975d65 + a517353 commit f916428

9 files changed

Lines changed: 409 additions & 288 deletions

‎docs/source/diffpy-agent.rst‎

Lines changed: 236 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,236 @@
1+
:tocdepth: -1
2+
3+
DiffPy Agent Interface
4+
=======================
5+
This interface is provided for agents, e.g. ``Claude Code`` and ``Codex``,
6+
which mainly utilizes the "tool" concept applied in most agent frameworks.
7+
After connecting these tools to an agent, users can invoke DiffPy
8+
functionalities and automate PDF refinements through conversation.
9+
10+
After you have installed ``diffpy.apps``, the next step is to connect it to
11+
your local agent. ``diffpy.apps`` server should be able to connect to any
12+
Desktop agent that supports the MCP (Model Context Protocol), and we have provided
13+
instructions for :ref:`connect_claude_desktop` and :ref:`connect_chatgpt_desktop` below.
14+
15+
.. _mcp_setup:
16+
17+
Setup
18+
-----
19+
20+
.. _connect_claude_desktop:
21+
Connect to Claude Desktop
22+
~~~~~~~~~~~~~~~~~~~~~~~~~
23+
1. Copy the path to the conda executable. There are many commands available,
24+
here are two examples
25+
26+
.. code-block:: bash
27+
28+
whereis conda # linux or macOS terminal
29+
where.exe conda # windows powershell
30+
31+
2. Install ``Claude Desktop`` (hereafter referred to as ``Claude``).
32+
3. Open ``Claude`` and open "Settings".
33+
4. Navigate to the "Developer" section.
34+
5. In the "Local MCP servers" region, click "Edit Config" and Open the configuration file. It's name should be ``claude_desktop_config.json``.
35+
36+
.. Figure:: img/claude_edit_config.png
37+
:align: center
38+
39+
Figure 1: Screenshot of "Edit Config" in ``Claude``.
40+
41+
6. Add the following configuration, and replace ``</path/to/conda>`` with the path to your conda executable and ``<conda_env_name>`` with the name of your conda environment.
42+
43+
.. code-block:: json
44+
45+
"mcpServers": {
46+
"diffpy.apps": {
47+
"command": "</path/to/conda>",
48+
"args": [
49+
"run",
50+
"--no-capture-output",
51+
"-n",
52+
"<conda_env_name>",
53+
"python",
54+
"-m",
55+
"diffpy.apps.refinebase.refinement_server"
56+
]
57+
}
58+
}
59+
60+
For example, If Mr Neutron installed ``diffpy.apps`` in the ``diffpy_apps``
61+
conda environment, his ``claude_desktop_config.json`` in the Linux/macOS system
62+
would look like this:
63+
64+
.. code-block:: json
65+
66+
{
67+
"mcpServers": {
68+
"diffpy.apps": {
69+
"command": "/path/to/bin/conda",
70+
"args": [
71+
"run",
72+
"--no-capture-output",
73+
"-n",
74+
"diffpy_apps",
75+
"python",
76+
"-m",
77+
"diffpy.apps.refinebase.refinement_server"
78+
]
79+
}
80+
},
81+
"other_configurations": "other_configurations"
82+
}
83+
84+
, and in the Windows system, it would look like this:
85+
86+
.. code-block:: json
87+
88+
{
89+
"mcpServers": {
90+
"diffpy.apps": {
91+
"command": "C:\\path\\to\\bin\\conda.bat",
92+
"args": [
93+
"run",
94+
"--no-capture-output",
95+
"-n",
96+
"diffpy_apps",
97+
"python",
98+
"-m",
99+
"diffpy.apps.refinebase.refinement_server"
100+
]
101+
}
102+
},
103+
"other_configurations": "other_configurations"
104+
}
105+
106+
107+
108+
7. Restart the ``Claude``.
109+
110+
8. Go to the same "Local MCP servers" section and verify that the
111+
``diffpy.apps`` server is listed and active.
112+
113+
.. figure:: img/claude_validate.png
114+
:align: center
115+
116+
Figure 2: Screenshot of active ``diffpy.apps`` server in ``Claude``.
117+
118+
119+
.. _connect_chatgpt_desktop:
120+
Connect to ChatGPT Desktop
121+
~~~~~~~~~~~~~~~~~~~~~~~~~~
122+
1. Copy the path to the conda executable. There are many commands available,
123+
here are two examples
124+
125+
.. code-block:: bash
126+
127+
whereis conda # linux or macOS terminal
128+
where.exe conda # windows powershell
129+
130+
1. Install ``ChatGPT Desktop`` (hereafter referred to as ``ChatGPT``).
131+
2. Open ``~/.codex/config.toml``.
132+
3. Add the following configuration, and replace ``<path/to/python>`` with the path to the Python executable in your conda environment.
133+
134+
.. code-block:: toml
135+
136+
[mcp_servers.diffpy_apps]
137+
command = "<path/to/conda>"
138+
args = [
139+
"run",
140+
"--no-capture-output",
141+
"-n",
142+
"<conda_env_name>",
143+
"python",
144+
"-m",
145+
"diffpy.apps.refinebase.refinement_server"
146+
]
147+
148+
.. note::
149+
150+
In Windows, please make sure the full path is separated by
151+
double backslashes (e.g., ``C:\\path\\to\\bin\\conda.bat``).
152+
153+
154+
4. Restart the ``ChatGPT``.
155+
156+
5. Open "Settings", and navigate to the "Integration" section. Open
157+
"Plugins" tab, and verify that the ``diffpy.apps`` server is listed in the
158+
"MCPs" field and active.
159+
160+
.. figure:: img/chatgpt_validate.png
161+
:align: center
162+
163+
Figure 2: Screenshot of active ``diffpy.apps`` server in ``ChatGPT``.
164+
165+
166+
Example Usage
167+
-------------
168+
Once you ``diffpy.apps`` MCP server is running, you can interact with it
169+
through the agent.
170+
171+
Here is a simple example of conducting Ni structure refinement.
172+
173+
1. Download the :download:`Ni.gr<data/Ni.gr>` and :download:`Ni.cif<data/Ni.cif>`
174+
files to your working directory.
175+
176+
2. Open ``Claude``, launch the "Code" tab or select "Cowork" in "Chat or Cowork"
177+
tab.
178+
179+
3. Add the working directory folder to the ``Claude``.
180+
181+
4. Start your conversation! For example, try to ask
182+
*Tell me what can diffpy.apps do and how it can help me refine the
183+
Ni.cif against the Ni.gr.*
184+
185+
186+
How to add Diffpy agent skills
187+
------------------------------
188+
189+
Another advantage of using the Diffpy agent is that its behavior can be
190+
tuned to suit specific tasks and workflows by adding custom skills and
191+
context.
192+
193+
We have prepared a basic skill that you can readily deploy and use with the
194+
Diffpy agent.
195+
196+
To use it, run
197+
198+
.. code-block:: bash
199+
200+
diffpy-app agentify
201+
202+
``claude`` and ``codex`` agent skills are supported. By default, it is
203+
deployed as the ``claude`` agent skill. Use the ``--agent`` option to
204+
specify the specific agent:
205+
206+
.. code-block:: bash
207+
208+
diffpy-app agentify --agent codex
209+
210+
To deploy the agentic skill to the system directory, use the ``--system`` flag:
211+
212+
.. code-block:: bash
213+
214+
diffpy-app agentify --system
215+
216+
To update the existing ``diffpy.cmi`` agentic skill, use the ``--update`` flag:
217+
218+
.. code-block:: bash
219+
220+
diffpy-app agentify --update
221+
222+
223+
How to contribute Diffpy agent skills
224+
-------------------------------------
225+
226+
Skills are simply markdown files providing context for the agents.
227+
They help to enable the agent to follow the best practices, and to
228+
efficiently perform workflows sharing similar patterns.
229+
Please refer to the documentation from your favorite agent platform, such as
230+
`Claude Documentation <https://platform.claude.com/docs/en/agents-and-tools/agent-skills/overview>`_
231+
for more details.
232+
233+
``diffpy-app agentify`` fetches our prepared agent skills from
234+
`cmi-agent-skills <https://github.com/diffpy/cmi-agent-skills>`_ GitHub repository.
235+
If you are willing to contribute your skills, you can submit Pull Requests in
236+
the same repository. Thanks for sharing your work with the community!

‎docs/source/diffpy-macro.rst‎

Lines changed: 134 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,134 @@
1+
:tocdepth: -1
2+
3+
DiffPy Macro Interface
4+
=======================
5+
6+
Diffpy macro files can be executed using the ``runmacro`` application.
7+
8+
.. code-block:: bash
9+
10+
diffpy-app runmacro <macro_file.dp-in>
11+
12+
To follow the example,
13+
14+
1. download the example files from :download:`here <../example/runmacro_example.zip>`
15+
16+
2. extract the downloaded files and navigate to the extracted directory
17+
18+
.. code-block:: bash
19+
20+
mv /path/to/runmacro runmacro_example.zip working_directory
21+
cd working_directory
22+
unzip runmacro_example.zip
23+
24+
3. run the macro using the ``runmacro`` application
25+
26+
.. code-block:: bash
27+
28+
diffpy-app runmacro example_macro.dp-in
29+
30+
How to write macro
31+
~~~~~~~~~~~~~~~~~~
32+
33+
Let's still use the Ni example created earlier, but this time we will
34+
write the macro file from scratch.
35+
36+
1. Prepare the structure and profile file you want to work with.
37+
38+
.. note::
39+
40+
The structure file is a ``.cif`` file representing the atomic arrangement in
41+
your sample, and the profile file is a ``.gr`` file containing the
42+
experimental data.
43+
44+
Start the macro file with the following two lines:
45+
46+
.. code-block:: text
47+
48+
load structure G1 from "path/to/structure.cif"
49+
load profile exp_ni from "path/to/profile.gr"
50+
51+
``G1`` and ``exp_ni`` are the identifiers used in the macro to refer to the
52+
structure and profile files, respectively. Quotes ``""`` are must to specify
53+
the file paths.
54+
55+
2. (Optional) Declare the space group of the structure.
56+
57+
.. code-block:: text
58+
59+
set G1 spacegroup as Fm-3m
60+
61+
``G1`` is the identifier for the structure file loaded earlier. Space group
62+
symmetry ``Fm-3m`` is preserved during the refinement. You can also set
63+
it to be ``auto`` to use the one automatically parsed from the structure file.
64+
But if space group is not provided, nor can it be determined from the structure
65+
file, it will be considered as ``P1`` space group.
66+
67+
3. (Optional) Set the calculation parameters for the refinement.
68+
69+
.. code-block:: text
70+
71+
set exp_ni calculation_range as 0.5 20.0 0.01 # r_min, r_max, r_step
72+
set exp_ni q_range as 0.5 20.0 # q_min, q_max
73+
74+
``exp_ni`` is the identifier for the profile file loaded earlier.
75+
``calculation_range`` specifies the range and step size for the calculation,
76+
while ``q_range`` specifies the range of Q values to be used in the refinement.
77+
If calculation parameters are not set, it will use the ones
78+
that are defined in the profile file.
79+
80+
81+
4. Create the refinement equation.
82+
83+
.. code-block:: text
84+
85+
create equation variables s0
86+
set equation as "G1*s0"
87+
88+
``G1`` is the identifier for the structure file loaded earlier. In the
89+
equation, it represents the PDF data generated from the structure `G1`.
90+
``s0`` is created to count for the scaling factor.
91+
92+
5. Store the results.
93+
94+
.. code-block:: text
95+
96+
save to "output_results.json"
97+
98+
The results of the refinement will be saved to a file
99+
named ``output_results.json``.
100+
101+
6. List variables to be refined.
102+
103+
.. code-block:: text
104+
105+
variables:
106+
---
107+
- G1.a: 3.52
108+
- s0: 0.4
109+
- G1.Uiso_0: 0.005
110+
- G1.delta2: 2
111+
- qdamp: 0.04
112+
- qbroad: 0.02
113+
---
114+
115+
Only variables listed in this section will be refined during the
116+
execution of the macro, and the variables will also be refined in that order.
117+
Variables with initial values specified here will be used as the
118+
starting point for the refinement.
119+
120+
.. note::
121+
The naming of variables follows the format
122+
``structure_identifier.parameter``,
123+
``profile_parameter``, or
124+
``equation_parameter``.
125+
126+
For parameters belonging to a specific atom in the parameter,
127+
the naming follows the format ``structure_identifier.parameter_atomindex``.
128+
e.g. ``G1.Uiso_0`` here refers to the Uiso parameter of the first atom in
129+
the structure ``G1``.
130+
131+
For constrained parameters, it will use the first parameter in the
132+
constraint. e.g. Here, lattice parameter ``a=b=c``,
133+
and ``Usio_0=Uiso_i, i=1,2,3``, ``a`` and ``Uiso_0`` are used as the
134+
reference variables.

0 commit comments

Comments
 (0)