ed-mcp 0.0.0-stage → 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Seth Osher
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/LICENSES/Apache-2.0.txt

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/NOTICE

@@ -0,0 +1,12 @@
+ed-mcp
+Copyright (c) 2026 Seth Osher. Licensed under the MIT License (see LICENSE).
+
+src/catalog/data/engineers.json is derived from EliteDangerousCore
+(https://github.com/EDDiscovery/EliteDangerousCore), Engineers.cs,
+Copyright 2022-2024 EDDiscovery development team, licensed under the
+Apache License, Version 2.0 (http://www.apache.org/licenses/LICENSE-2.0).
+A copy of the licence is in LICENSES/Apache-2.0.txt.
+The data was converted from C# to JSON.
+
+Elite Dangerous game data is the intellectual property of Frontier Developments plc.
+This project is not affiliated with Frontier Developments, Inara, EDSM, Spansh or EDCD.

package/README.md

@@ -1,3 +1,170 @@
-# Temporary Holding Version
+# ed-mcp
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+ed-mcp connects Claude to Elite Dangerous. Claude can then read your commander data and plan with you.
+
+With ed-mcp, Claude can:
+
+- plan a ship build: the modules to buy, the engineering, the materials and the engineers to visit, and the route to all of them,
+- work out which materials you are short of and the trades that cover them,
+- find the best station for a module, ship or service, ranked by travel time and price,
+- plan trade runs and loops, and find where to sell or buy a commodity,
+- put the stops for your accepted missions in the best order,
+- read your game journal for your location, ship, cargo, materials, missions and engineer progress.
+
+### Why use it
+
+Inara, EDSM, Spansh, EDSY and the community wikis already have this data, and you can do all of this on their sites. ed-mcp does not replace them. It lets Claude use them together, with your game journal, in one conversation. Some commanders find it easier to ask a question in their own words than to use several sites.
+
+ed-mcp runs on your computer. It keeps your plans and settings on your computer. It reads from Inara, EDSM, Frontier and Spansh, and it downloads game data from GitHub.
+
+ed-mcp is not affiliated with Frontier Developments, Inara, EDSM or Spansh.
+
+## What you can ask
+
+- "Here is my build from EDSY. Make a plan for the modules I need to buy or engineer. Tell me the materials I am short of and where to trade for them."
+- "Where is the nearest Guardian technology broker?"
+- "What do I need for grade 5 dirty drives?"
+- "Find me a trade route from here. I have 400 t of cargo."
+- "Where can I sell 200 t of gold near Atlas?"
+- "Find me a trade loop from this station that I can run for an hour."
+- "Plan the best order for my passenger missions."
+- "Plan the route for my Corsair build plan."
+- "From now on, ignore stations more than 2,000 ls from the star."
+
+## Install
+
+### Claude Desktop
+
+1. Download `ed-mcp-<version>.mcpb` from the [Releases](https://github.com/pilotso11/ed-mcp/releases) page.
+2. Open the file. Claude Desktop shows the ed-mcp settings form.
+3. Fill in the fields for the services that you use (see [Connect your accounts](#connect-your-accounts)). All fields are optional.
+
+To make sure that the file came from this project, run the GitHub CLI command below. It shows that the ed-mcp release workflow built the file from this repository. This command works for version 0.1.1 and later.
+
+```bash
+gh attestation verify ed-mcp-<version>.mcpb --repo pilotso11/ed-mcp
+```
+
+### Claude Code
+
+Run this command. Put your own values in place of `<...>`:
+
+```bash
+claude mcp add ed-mcp -s user \
+  -e INARA_API_KEY=<key> -e INARA_CMDR=<commander name> \
+  -e EDSM_API_KEY=<key> -e EDSM_CMDR=<commander name> \
+  -- npx -y ed-mcp
+```
+
+- Keep `ed-mcp` directly after `add`. The `-e` options take every word after them until the `--`.
+- Leave out the `-e` options for a service that you do not use.
+- On a Mac, also add `-e ED_JOURNAL_DIR=<folder>` (see [Your game journal](#your-game-journal)).
+
+Then start a new Claude Code session. To make sure that the server works, ask Claude "What is my journal status?".
+
+## Connect your accounts
+
+Every account is optional. Without one, the tools for that service tell Claude which setting is missing. The game data, station search, route and plan tools work with no account.
+
+| Service  | What it gives Claude                                     | What you need                                                        |
+| -------- | -------------------------------------------------------- | -------------------------------------------------------------------- |
+| Journal  | Location, ship, cargo, materials, missions, engineers    | The game journal folder (see below)                                  |
+| Inara    | Ranks, squadron, main ship, community goals              | Your API key (inara.cz, Settings, Inara API) and commander name      |
+| EDSM     | Last known location, materials and cargo                 | Your API key (edsm.net, Settings, API Key) and commander name        |
+| Frontier | Current ship with engineering, location and fleet        | A Frontier login in your browser. No key is necessary.               |
+
+To log in to Frontier, ask Claude "Log me in to Frontier". Claude gives you a link. Open the link and sign in. Then tell Claude that you are done. The login lasts 25 days. If you log in to ed-mcp on another computer, the old login ends.
+
+The game journal is the best source for most questions. It is on your computer and it is current while you play. Inara and EDSM show data from your last sync to them.
+
+### All settings
+
+| Setting          | Meaning                                                                                                   |
+| ---------------- | --------------------------------------------------------------------------------------------------------- |
+| `INARA_API_KEY`  | Your Inara API key                                                                                        |
+| `INARA_CMDR`     | Your in-game commander name                                                                               |
+| `EDSM_API_KEY`   | Your EDSM API key                                                                                         |
+| `EDSM_CMDR`      | Your commander name on EDSM                                                                               |
+| `ED_JOURNAL_DIR` | The game journal folder. On Windows, the default is the game's folder. Use a full path or one that starts with `~`. |
+| `ED_MCP_PLANS`   | A different file for your plans. Use a full path or one that starts with `~`. The default is `plans.json` in the settings folder (see [Your data](#your-data)). |
+
+Inara needs both of its settings. EDSM needs both of its settings.
+
+## Your game journal
+
+Elite Dangerous writes a journal while you play. ed-mcp reads it and never changes it.
+
+**If Claude runs on your gaming PC**, ed-mcp finds the journal by itself. The folder is `%USERPROFILE%\Saved Games\Frontier Developments\Elite Dangerous`. If Windows moved your Saved Games folder (for example, into OneDrive), set `ED_JOURNAL_DIR` to the real folder.
+
+**If Claude runs on a Mac**, copy the journal to the Mac with Syncthing:
+
+1. Install Syncthing on the PC and on the Mac (syncthing.net).
+2. On the PC, add the folder `%USERPROFILE%\Saved Games\Frontier Developments\Elite Dangerous`. Set the folder type to **Send Only**.
+3. Pair the two devices. Share the folder with the Mac.
+4. On the Mac, accept the folder into a local folder, for example `~/EliteDangerous`. Set the folder type to **Receive Only**.
+5. Set `ED_JOURNAL_DIR` to that folder. In Claude Desktop, use the Journal folder field.
+6. Ask Claude "What is my journal status?". While you play, the newest journal is a few minutes old.
+
+Do not share `%LOCALAPPDATA%\Frontier Developments\Elite Dangerous`. That folder has the same name, but it holds only the game's settings. If you share it by mistake, the journal status tells you.
+
+The journal tools warn you when the newest entry is more than 30 minutes old. Then the game is not running, or Syncthing has stopped.
+
+## Plans
+
+Claude can save plans for you, for example a ship build with its modules, engineering and materials. Ask Claude to add items, mark them done, or export the plan as a Markdown file. To keep a plan in a project folder, export it as JSON and import it again later with `plan_import`. The plans stay on your computer, in `plans.json` in the settings folder (see [Your data](#your-data)). To keep them in another place, for example a folder that you back up, set `ED_MCP_PLANS`.
+
+## Preferences
+
+ed-mcp ranks stations by travel time and price. Your preferences control which stations it uses. To change a preference, tell Claude, for example "Avoid surface stations" or "My time is worth 50M credits an hour". The change stays for future sessions. For one question only, say so: "Just this once, include fleet carriers."
+
+| Preference                       | Default                                                                    |
+| -------------------------------- | -------------------------------------------------------------------------- |
+| Distance from the star           | Up to 1,000 ls. A station further out is used only when no other matches. |
+| Surface stations                 | Avoided. They are used only when no orbital station matches.               |
+| Fleet carriers                   | Excluded                                                                   |
+| Megaships                        | Allowed                                                                    |
+| Landing pad size                 | Taken from your current ship                                               |
+| Jump range                       | Taken from your current ship (85% of its best range)                      |
+| Value of your time               | 20M credits an hour                                                        |
+
+The value of your time decides between a cheap station far away and a dearer one nearby. At 20M credits an hour, one extra minute of travel is worth about 333,000 credits.
+
+The travel times come from about 1,300 timed trips in a commander's journals, flown with supercruise assist. If you fly faster, tell Claude "I fly about 40% faster in supercruise". For all the details, see the [tool reference](docs/tools.md#travel-model).
+
+## Limits
+
+- Station, market and trade data come from Spansh. Market prices can be some hours or days old. The results show the age of each price. Spansh gets prices from EDDN, so a market that you open while you run a tool such as EDMC reaches Spansh within minutes.
+- Trade routes and first-time mission routes can take a minute or more. If Spansh is still working, Claude asks again.
+- Trade routes go one way. Trade loops use two or three stations and one commodity on each leg. Their scores use one price snapshot, and prices fall as you repeat a loop.
+- ed-mcp cannot see the mission board. It plans routes only for missions that you accepted.
+- Material plans ignore the storage limit for each material grade.
+
+## Your data
+
+ed-mcp keeps these files on your computer:
+
+| Data                         | File                                         |
+| ---------------------------- | -------------------------------------------- |
+| Plans                        | `plans.json`, or the file in `ED_MCP_PLANS`  |
+| Preferences                  | `preferences.json`                           |
+| Frontier login               | `capi-token.json`, readable only by you      |
+| Game data and cached results | The cache folder                             |
+
+The files are in these folders:
+
+| System  | Settings folder                | Cache folder                       |
+| ------- | ------------------------------ | ---------------------------------- |
+| macOS   | `~/Library/Preferences/ed-mcp` | `~/Library/Caches/ed-mcp`          |
+| Windows | `%APPDATA%\ed-mcp\Config`      | `%LOCALAPPDATA%\ed-mcp\Cache`      |
+| Linux   | `~/.config/ed-mcp`             | `~/.cache/ed-mcp`                  |
+
+ed-mcp sends your API keys only to the service that they belong to. On first use, it downloads game data (modules, blueprints and materials) from the coriolis-data and FDevIDs projects on GitHub. Then it looks for new versions once a week. To get new data at once, ask Claude to refresh the game data.
+
+## More information
+
+- [Tool reference](docs/tools.md): what each tool does, its inputs and its results.
+- [Contributing](CONTRIBUTING.md): development, releases and service registrations.
+
+## Licence
+
+MIT. See `NOTICE` for third-party data.