everos-mcp 0.1.0__tar.gz
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- everos_mcp-0.1.0/.github/workflows/ci.yml +24 -0
- everos_mcp-0.1.0/.github/workflows/release.yml +84 -0
- everos_mcp-0.1.0/.gitignore +7 -0
- everos_mcp-0.1.0/Dockerfile +20 -0
- everos_mcp-0.1.0/LICENSE +21 -0
- everos_mcp-0.1.0/PKG-INFO +338 -0
- everos_mcp-0.1.0/README.md +309 -0
- everos_mcp-0.1.0/SECURITY.md +45 -0
- everos_mcp-0.1.0/pyproject.toml +52 -0
- everos_mcp-0.1.0/scripts/smoke_test.py +86 -0
- everos_mcp-0.1.0/src/everos_mcp/__init__.py +3 -0
- everos_mcp-0.1.0/src/everos_mcp/client.py +206 -0
- everos_mcp-0.1.0/src/everos_mcp/config.py +122 -0
- everos_mcp-0.1.0/src/everos_mcp/conversation.py +252 -0
- everos_mcp-0.1.0/src/everos_mcp/guard.py +96 -0
- everos_mcp-0.1.0/src/everos_mcp/oauth.py +140 -0
- everos_mcp-0.1.0/src/everos_mcp/server.py +772 -0
- everos_mcp-0.1.0/tests/test_everos_mcp.py +1033 -0
- everos_mcp-0.1.0/uv.lock +1061 -0
|
@@ -0,0 +1,24 @@
|
|
|
1
|
+
name: CI
|
|
2
|
+
|
|
3
|
+
on:
|
|
4
|
+
push:
|
|
5
|
+
branches: [main]
|
|
6
|
+
pull_request:
|
|
7
|
+
|
|
8
|
+
jobs:
|
|
9
|
+
test:
|
|
10
|
+
runs-on: ubuntu-latest
|
|
11
|
+
strategy:
|
|
12
|
+
matrix:
|
|
13
|
+
python: ["3.10", "3.13"]
|
|
14
|
+
steps:
|
|
15
|
+
- uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4
|
|
16
|
+
- uses: astral-sh/setup-uv@d4b2f3b6ecc6e67c4457f6d3e41ec42d3d0fcb86 # v5
|
|
17
|
+
with:
|
|
18
|
+
python-version: ${{ matrix.python }}
|
|
19
|
+
- run: uv sync --dev --locked
|
|
20
|
+
- run: uv run ruff check .
|
|
21
|
+
- run: uv run pytest -q
|
|
22
|
+
- name: pytest against the minimum supported mcp
|
|
23
|
+
if: matrix.python == '3.10'
|
|
24
|
+
run: uv run --isolated --with "mcp==1.14.0" --with pytest --with-editable . pytest -q
|
|
@@ -0,0 +1,84 @@
|
|
|
1
|
+
# Publishes to PyPI via Trusted Publishing (OIDC) — no stored token — then
|
|
2
|
+
# drafts the matching GitHub Release. Fires on a version tag (vX.Y.Z, plus PEP
|
|
3
|
+
# 440 pre-releases such as vX.Y.Zrc1). The `release` environment gates the
|
|
4
|
+
# upload behind manual approval: Settings → Environments → release → required
|
|
5
|
+
# reviewers.
|
|
6
|
+
#
|
|
7
|
+
# One-time setup on PyPI (account owner, cannot be done from CI):
|
|
8
|
+
# pypi.org → Your account → Publishing → add a pending publisher:
|
|
9
|
+
# project=everos-mcp, owner=EverMind-AI, repo=EverOS-MCP,
|
|
10
|
+
# workflow=release.yml, environment=release.
|
|
11
|
+
name: Release
|
|
12
|
+
|
|
13
|
+
on:
|
|
14
|
+
push:
|
|
15
|
+
tags:
|
|
16
|
+
- "v[0-9]+.[0-9]+.[0-9]+*"
|
|
17
|
+
|
|
18
|
+
permissions:
|
|
19
|
+
contents: read
|
|
20
|
+
|
|
21
|
+
jobs:
|
|
22
|
+
publish:
|
|
23
|
+
name: build + publish to PyPI
|
|
24
|
+
runs-on: ubuntu-latest
|
|
25
|
+
environment: release
|
|
26
|
+
permissions:
|
|
27
|
+
id-token: write # OIDC token for PyPI Trusted Publishing
|
|
28
|
+
contents: read
|
|
29
|
+
steps:
|
|
30
|
+
- uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4
|
|
31
|
+
- uses: astral-sh/setup-uv@d4b2f3b6ecc6e67c4457f6d3e41ec42d3d0fcb86 # v5
|
|
32
|
+
with:
|
|
33
|
+
python-version: "3.12"
|
|
34
|
+
|
|
35
|
+
# The tag must match the package version, so a mistyped tag can't
|
|
36
|
+
# publish the wrong release.
|
|
37
|
+
- name: Verify tag matches package version
|
|
38
|
+
run: |
|
|
39
|
+
tag="${GITHUB_REF_NAME#v}"
|
|
40
|
+
pkg="$(grep -m1 -E '^version = ' pyproject.toml | sed -E 's/^version = "(.+)"/\1/')"
|
|
41
|
+
mod="$(sed -nE 's/^__version__ = "(.+)"/\1/p' src/everos_mcp/__init__.py)"
|
|
42
|
+
if [ "$tag" != "$pkg" ] || [ "$tag" != "$mod" ]; then
|
|
43
|
+
echo "::error::tag v$tag, pyproject $pkg and __version__ $mod must all match"
|
|
44
|
+
exit 1
|
|
45
|
+
fi
|
|
46
|
+
|
|
47
|
+
- name: Test
|
|
48
|
+
run: uv sync --dev --locked && uv run ruff check . && uv run pytest -q
|
|
49
|
+
|
|
50
|
+
- name: Build
|
|
51
|
+
run: uv build --out-dir dist
|
|
52
|
+
|
|
53
|
+
# Install the built wheel into a clean environment and start it: catches
|
|
54
|
+
# a package that builds but is missing a module or an entry point.
|
|
55
|
+
- name: Smoke-test the wheel
|
|
56
|
+
run: |
|
|
57
|
+
uv run --isolated --no-project --with dist/*.whl everos-mcp --help
|
|
58
|
+
uv run --isolated --no-project --with dist/*.whl \
|
|
59
|
+
python -c "import everos_mcp.server, everos_mcp.oauth"
|
|
60
|
+
|
|
61
|
+
- name: Publish to PyPI (Trusted Publishing)
|
|
62
|
+
uses: pypa/gh-action-pypi-publish@dc37677b2e1c63e2034f94d8a5b11f265b73ba33 # v1.14.2
|
|
63
|
+
|
|
64
|
+
# Separate job so the publish job keeps `contents: read` next to its OIDC
|
|
65
|
+
# token. Left as a draft: a human reads the notes, then clicks Publish.
|
|
66
|
+
github-release:
|
|
67
|
+
name: draft the GitHub Release
|
|
68
|
+
needs: publish
|
|
69
|
+
runs-on: ubuntu-latest
|
|
70
|
+
permissions:
|
|
71
|
+
contents: write
|
|
72
|
+
steps:
|
|
73
|
+
- name: Create the draft release
|
|
74
|
+
env:
|
|
75
|
+
GH_TOKEN: ${{ github.token }}
|
|
76
|
+
TAG: ${{ github.ref_name }}
|
|
77
|
+
run: |
|
|
78
|
+
flags="--latest"
|
|
79
|
+
if ! echo "${TAG#v}" | grep -qE '^[0-9]+\.[0-9]+\.[0-9]+$'; then
|
|
80
|
+
flags="--prerelease --latest=false"
|
|
81
|
+
fi
|
|
82
|
+
# $flags is deliberately unquoted — it can carry two words.
|
|
83
|
+
gh release create "$TAG" --repo "$GITHUB_REPOSITORY" --draft $flags \
|
|
84
|
+
--title "everos-mcp ${TAG#v}" --generate-notes
|
|
@@ -0,0 +1,20 @@
|
|
|
1
|
+
# Pinned by digest; bump deliberately.
|
|
2
|
+
FROM ghcr.io/astral-sh/uv:python3.12-bookworm-slim@sha256:e5b65587bce7de595f299855d7385fe7fca39b8a74baa261ba1b7147afa78e58
|
|
3
|
+
|
|
4
|
+
WORKDIR /app
|
|
5
|
+
COPY pyproject.toml uv.lock README.md LICENSE ./
|
|
6
|
+
COPY src ./src
|
|
7
|
+
# Install exactly the locked dependency versions, then the package itself.
|
|
8
|
+
RUN uv export --frozen --no-dev --no-emit-project -o /tmp/requirements.txt \
|
|
9
|
+
&& uv pip install --system --no-cache -r /tmp/requirements.txt . \
|
|
10
|
+
&& rm /tmp/requirements.txt
|
|
11
|
+
|
|
12
|
+
# Holds no credentials: each request brings the caller's EverOS API key.
|
|
13
|
+
ENV EVEROS_MCP_TRANSPORT=http \
|
|
14
|
+
EVEROS_MCP_HOST=0.0.0.0 \
|
|
15
|
+
EVEROS_MCP_PORT=8765
|
|
16
|
+
EXPOSE 8765
|
|
17
|
+
USER nobody
|
|
18
|
+
# Same port variable the server reads, so overriding it keeps the check right.
|
|
19
|
+
HEALTHCHECK CMD python -c "import os, urllib.request; urllib.request.urlopen('http://127.0.0.1:%s/healthz' % os.environ.get('EVEROS_MCP_PORT', '8765'))"
|
|
20
|
+
ENTRYPOINT ["everos-mcp"]
|
everos_mcp-0.1.0/LICENSE
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 EverMind AI
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
|
@@ -0,0 +1,338 @@
|
|
|
1
|
+
Metadata-Version: 2.5
|
|
2
|
+
Name: everos-mcp
|
|
3
|
+
Version: 0.1.0
|
|
4
|
+
Summary: MCP server for EverOS — long-term memory for AI agents, backed by the EverOS Cloud Memory API (v2)
|
|
5
|
+
Project-URL: Homepage, https://evermind.ai
|
|
6
|
+
Project-URL: Documentation, https://docs.evermind.ai
|
|
7
|
+
Project-URL: Repository, https://github.com/EverMind-AI/EverOS-MCP
|
|
8
|
+
Project-URL: Issues, https://github.com/EverMind-AI/EverOS-MCP/issues
|
|
9
|
+
Project-URL: Console, https://everos.evermind.ai
|
|
10
|
+
Author-email: EverMind AI <service@evermind.ai>
|
|
11
|
+
License: MIT
|
|
12
|
+
License-File: LICENSE
|
|
13
|
+
Keywords: ai-agents,claude,evermind,everos,long-term-memory,mcp,memory,model-context-protocol
|
|
14
|
+
Classifier: Development Status :: 4 - Beta
|
|
15
|
+
Classifier: Intended Audience :: Developers
|
|
16
|
+
Classifier: License :: OSI Approved :: MIT License
|
|
17
|
+
Classifier: Operating System :: OS Independent
|
|
18
|
+
Classifier: Programming Language :: Python :: 3
|
|
19
|
+
Classifier: Programming Language :: Python :: 3.10
|
|
20
|
+
Classifier: Programming Language :: Python :: 3.11
|
|
21
|
+
Classifier: Programming Language :: Python :: 3.12
|
|
22
|
+
Classifier: Programming Language :: Python :: 3.13
|
|
23
|
+
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
|
|
24
|
+
Classifier: Topic :: Software Development :: Libraries
|
|
25
|
+
Requires-Python: >=3.10
|
|
26
|
+
Requires-Dist: httpx<1,>=0.27.0
|
|
27
|
+
Requires-Dist: mcp<2,>=1.14.0
|
|
28
|
+
Description-Content-Type: text/markdown
|
|
29
|
+
|
|
30
|
+
<div align="center" id="readme-top">
|
|
31
|
+
|
|
32
|
+

|
|
33
|
+
|
|
34
|
+
<h3 align="center">🧠 Long-term memory for any MCP client — the official EverOS <b>MCP server</b></h3>
|
|
35
|
+
|
|
36
|
+
<p align="center">
|
|
37
|
+
<a href="https://x.com/evermind"><img src="https://img.shields.io/badge/EverMind-000000?labelColor=gray&style=for-the-badge&logo=x&logoColor=white" alt="X"></a>
|
|
38
|
+
<a href="https://huggingface.co/EverMind-AI"><img src="https://img.shields.io/badge/🤗_HuggingFace-EverMind-F5C842?labelColor=gray&style=for-the-badge" alt="HuggingFace"></a>
|
|
39
|
+
<a href="https://discord.gg/gYep5nQRZJ"><img src="https://img.shields.io/badge/Discord-EverMind-404EED?labelColor=gray&style=for-the-badge&logo=discord&logoColor=white" alt="Discord"></a>
|
|
40
|
+
</p>
|
|
41
|
+
|
|
42
|
+
<p align="center">
|
|
43
|
+
<a href="https://pypi.org/project/everos-mcp/"><img src="https://img.shields.io/pypi/v/everos-mcp?color=2DABC2&style=for-the-badge" alt="PyPI"></a>
|
|
44
|
+
<img src="https://img.shields.io/pypi/pyversions/everos-mcp?style=for-the-badge" alt="Python">
|
|
45
|
+
<img src="https://img.shields.io/badge/license-MIT-green?style=for-the-badge" alt="License">
|
|
46
|
+
</p>
|
|
47
|
+
|
|
48
|
+
[Website](https://evermind.ai) · [Documentation](https://docs.evermind.ai) · [Console](https://everos.evermind.ai) · [GitHub](https://github.com/EverMind-AI/EverOS-MCP)
|
|
49
|
+
|
|
50
|
+
</div>
|
|
51
|
+
|
|
52
|
+
<br>
|
|
53
|
+
|
|
54
|
+
> **Which package?** This is **everos-mcp**: plug EverOS memory into Claude Code, Claude
|
|
55
|
+
> Desktop, Cursor, Codex, or any other MCP client, with no code.
|
|
56
|
+
>
|
|
57
|
+
> Calling EverOS from your own Python code? Use the [`everos-cloud`](https://pypi.org/project/everos-cloud/) SDK.
|
|
58
|
+
> Want to self-host? Run the open-source [`everos`](https://pypi.org/project/everos/) server, then point this package at it.
|
|
59
|
+
|
|
60
|
+
# EverOS MCP Server
|
|
61
|
+
|
|
62
|
+
Your AI assistant forgets everything when the session ends. **everos-mcp** gives it a
|
|
63
|
+
memory that lasts: it remembers what you told it, builds a profile of how you work, and
|
|
64
|
+
learns from how past tasks were solved, across every session and every machine.
|
|
65
|
+
|
|
66
|
+
## Why everos-mcp
|
|
67
|
+
|
|
68
|
+
- **Remembers across sessions** — facts, decisions, and preferences you mention are stored
|
|
69
|
+
and recalled by relevance whenever they matter, not dumped into every prompt.
|
|
70
|
+
- **Knows who you are** — EverOS distills a user profile (facts, traits, preferences) from
|
|
71
|
+
your conversations, and the assistant loads it at the start of each session.
|
|
72
|
+
- **Learns from experience** — record how a task was solved, tool calls included, and EverOS
|
|
73
|
+
distills it into reusable cases and skills the agent recalls next time.
|
|
74
|
+
- **Works on its own** — the server ships an autonomy protocol through MCP `instructions`,
|
|
75
|
+
so capable hosts load the profile, store new facts, and recall context without being asked.
|
|
76
|
+
- **Safe by default** — a credential guard refuses to store secrets, recalled memories are
|
|
77
|
+
fenced as data rather than instructions, and you can delete everything a session stored.
|
|
78
|
+
- **Cloud or self-hosted** — EverOS Cloud out of the box; one environment variable points it
|
|
79
|
+
at your own EverOS deployment.
|
|
80
|
+
|
|
81
|
+
## Quick start
|
|
82
|
+
|
|
83
|
+
1. Get an API key from the [EverOS Console](https://everos.evermind.ai/api-keys).
|
|
84
|
+
2. Make sure [`uv`](https://docs.astral.sh/uv/getting-started/installation/) is installed
|
|
85
|
+
(`uvx` runs the server without a manual install).
|
|
86
|
+
3. Add the server to your client:
|
|
87
|
+
|
|
88
|
+
**Claude Code**
|
|
89
|
+
|
|
90
|
+
```bash
|
|
91
|
+
claude mcp add everos -e EVEROS_API_KEY=sk-... -- uvx everos-mcp
|
|
92
|
+
```
|
|
93
|
+
|
|
94
|
+
**Codex**
|
|
95
|
+
|
|
96
|
+
```bash
|
|
97
|
+
codex mcp add everos --env EVEROS_API_KEY=sk-... -- uvx everos-mcp
|
|
98
|
+
```
|
|
99
|
+
|
|
100
|
+
**Claude Desktop, Cursor, and other JSON-configured clients** — add this to the client's
|
|
101
|
+
MCP config (`claude_desktop_config.json`, `~/.cursor/mcp.json`, …):
|
|
102
|
+
|
|
103
|
+
```json
|
|
104
|
+
{
|
|
105
|
+
"mcpServers": {
|
|
106
|
+
"everos": {
|
|
107
|
+
"command": "uvx",
|
|
108
|
+
"args": ["everos-mcp"],
|
|
109
|
+
"env": {
|
|
110
|
+
"EVEROS_API_KEY": "sk-..."
|
|
111
|
+
}
|
|
112
|
+
}
|
|
113
|
+
}
|
|
114
|
+
}
|
|
115
|
+
```
|
|
116
|
+
|
|
117
|
+
That's it. Tell your assistant something worth remembering, start a new session, and ask
|
|
118
|
+
about it.
|
|
119
|
+
|
|
120
|
+
## Tools
|
|
121
|
+
|
|
122
|
+
| Tool | Purpose |
|
|
123
|
+
|---|---|
|
|
124
|
+
| `search_memory` | Relevance search over stored memories (optionally with the user profile) |
|
|
125
|
+
| `add_memory` | Store a durable fact or exchange; saves in the background by default (`wait=true` to block until it is searchable) |
|
|
126
|
+
| `get_profile` | The synthesized user profile (facts, traits, preferences) |
|
|
127
|
+
| `list_memories` | Chronological, paginated browsing |
|
|
128
|
+
| `forget_session` | Delete what this connection stored (memories + cases distilled from its trajectories); the profile and learned skills are kept |
|
|
129
|
+
| `record_trajectory` | Record how a task was solved (incl. tool calls) for future reuse |
|
|
130
|
+
| `recall_agent_experience` | Search distilled cases/skills relevant to the task at hand |
|
|
131
|
+
|
|
132
|
+
Read-only tools carry the MCP `readOnlyHint` annotation, so hosts can run them without a
|
|
133
|
+
permission prompt; `forget_session` is marked destructive.
|
|
134
|
+
|
|
135
|
+
**Good to know**
|
|
136
|
+
|
|
137
|
+
- Profile updates and case/skill distillation run in an offline pipeline and land seconds
|
|
138
|
+
to minutes after the write.
|
|
139
|
+
- A background save that fails is reported on the next tool result, so the model never
|
|
140
|
+
silently believes something was remembered.
|
|
141
|
+
- Trajectories need more than three tool-call rounds to pass the distillation quality
|
|
142
|
+
gate; shorter ones are stored as episodes but produce no case.
|
|
143
|
+
|
|
144
|
+
## Configuration
|
|
145
|
+
|
|
146
|
+
| Env var | Required | Default | Meaning |
|
|
147
|
+
|---|---|---|---|
|
|
148
|
+
| `EVEROS_API_KEY` | yes (cloud) | — | API key; issued per environment |
|
|
149
|
+
| `EVEROS_USER_ID` | no | `default-user` | Id owning the memories: one memory per API key by default, the same on every machine. Set it to keep several people apart under one key; up to 100 letters, digits and `_ . @ + -` |
|
|
150
|
+
| `EVEROS_BASE_URL` | no | `https://api.evermind.ai` | API endpoint; point at your own deployment for self-hosted EverOS |
|
|
151
|
+
| `EVEROS_APP_ID` / `EVEROS_PROJECT_ID` | no | `default` | Business scope |
|
|
152
|
+
| `EVEROS_SESSION_ID` | no | `mcp-<user_id>-<random>` | Session everything is stored under; a fresh one per server process. Setting a fixed value makes `forget_session` delete everything ever stored under it, by any run |
|
|
153
|
+
| `EVEROS_ASSISTANT_SENDER_ID` | no | `assistant-<user_id>` | Agent identity for trajectories and recalled experience. Per user by default; set the same value for everyone to pool agent experience across a team (their trajectories then become visible to each other) |
|
|
154
|
+
|
|
155
|
+
### Self-hosted / open-source EverOS
|
|
156
|
+
|
|
157
|
+
Set `EVEROS_BASE_URL` to your own [EverOS](https://github.com/EverMind-AI/EverOS)
|
|
158
|
+
deployment. No API key is required when the URL is not an evermind.ai host.
|
|
159
|
+
|
|
160
|
+
```bash
|
|
161
|
+
claude mcp add everos -e EVEROS_BASE_URL=http://127.0.0.1:8000 -- uvx everos-mcp
|
|
162
|
+
```
|
|
163
|
+
|
|
164
|
+
## Security
|
|
165
|
+
|
|
166
|
+
Every write path runs a credential guard before content leaves the process. It scans
|
|
167
|
+
every string in the payload — including trajectory tool-call arguments and tool results —
|
|
168
|
+
for high-confidence secret formats (API keys, AWS/GitHub/Slack/Stripe tokens, private
|
|
169
|
+
keys, JWTs, bearer tokens, URLs with embedded passwords, `password=`/`api_key:`-style
|
|
170
|
+
assignments) and refuses the write with no bypass flag. Long-term memory is not a safe
|
|
171
|
+
place for secrets; store a reference instead.
|
|
172
|
+
|
|
173
|
+
Recalled memories are returned marked as stored data, and the server instructions tell
|
|
174
|
+
the model never to follow directions found inside them.
|
|
175
|
+
|
|
176
|
+
Found a vulnerability? Please report it privately — see the
|
|
177
|
+
[security policy](https://github.com/EverMind-AI/EverOS-MCP/blob/main/SECURITY.md).
|
|
178
|
+
|
|
179
|
+
## Remote server (streamable HTTP)
|
|
180
|
+
|
|
181
|
+
The same package runs as a shared, hosted MCP server. It holds no credentials of its
|
|
182
|
+
own: every request brings the caller's EverOS API key, which is forwarded to the EverOS
|
|
183
|
+
API and never stored.
|
|
184
|
+
|
|
185
|
+
```bash
|
|
186
|
+
everos-mcp --transport http --host 0.0.0.0 --port 8765
|
|
187
|
+
```
|
|
188
|
+
|
|
189
|
+
Clients connect with their own key:
|
|
190
|
+
|
|
191
|
+
```bash
|
|
192
|
+
claude mcp add --transport http everos https://mcp.example.com/mcp \
|
|
193
|
+
--header "Authorization: Bearer sk-..."
|
|
194
|
+
```
|
|
195
|
+
|
|
196
|
+
<details>
|
|
197
|
+
<summary><b>Request headers, server settings, and deployment notes</b></summary>
|
|
198
|
+
|
|
199
|
+
<br>
|
|
200
|
+
|
|
201
|
+
| Request header | Required | Meaning |
|
|
202
|
+
|---|---|---|
|
|
203
|
+
| `Authorization: Bearer <key>` | yes | The caller's EverOS API key. Missing → HTTP 401 with `WWW-Authenticate: Bearer` |
|
|
204
|
+
| `X-EverOS-User-Id` | no | Whose memory within the key's space (default `default-user`) |
|
|
205
|
+
|
|
206
|
+
| Server env var | Default | Meaning |
|
|
207
|
+
|---|---|---|
|
|
208
|
+
| `EVEROS_BASE_URL` | `https://api.evermind.ai` | EverOS API the server talks to |
|
|
209
|
+
| `EVEROS_APP_ID` / `EVEROS_PROJECT_ID` | `default` | Business scope for every caller |
|
|
210
|
+
| `EVEROS_MCP_HOST` / `EVEROS_MCP_PORT` | `127.0.0.1` / `8765` | Bind address (same as `--host` / `--port`) |
|
|
211
|
+
| `EVEROS_MCP_ALLOWED_HOSTS` | — | Comma-separated public host names to accept (DNS-rebinding protection) |
|
|
212
|
+
| `EVEROS_MCP_PUBLIC_URL` | — | Public base URL of this server, e.g. `https://mcp.example.com` |
|
|
213
|
+
| `EVEROS_MCP_AUTHORIZATION_SERVER` | — | OAuth issuer that signs users in. When set, the server publishes RFC 9728 metadata at `/.well-known/oauth-protected-resource/mcp` and points to it from the 401 challenge |
|
|
214
|
+
| `EVEROS_MCP_INTROSPECTION_URL` / `EVEROS_MCP_INTROSPECTION_SECRET` | — | OAuth mode (both required, together with the authorization server): bearer tokens are verified at this RFC 7662 endpoint (audience must be this server) and exchanged for the EverOS API key the user granted. The token itself is never forwarded upstream, as the MCP authorization spec requires. Contract: [`oauth.py`](https://github.com/EverMind-AI/EverOS-MCP/blob/main/src/everos_mcp/oauth.py) |
|
|
215
|
+
|
|
216
|
+
Deployment notes:
|
|
217
|
+
|
|
218
|
+
- Terminate TLS at the ingress; `GET /healthz` is the liveness probe.
|
|
219
|
+
- Each MCP session lives in the memory of the replica that created it. With more than
|
|
220
|
+
one replica, route by the `Mcp-Session-Id` header (sticky sessions).
|
|
221
|
+
- An API key is the trust boundary: anyone holding a key can read and write every user id
|
|
222
|
+
within that key's space (`X-EverOS-User-Id` is chosen by the caller). Give separate
|
|
223
|
+
people separate keys when that matters.
|
|
224
|
+
- Conversations are isolated by (API key, user, MCP session): one caller never sees
|
|
225
|
+
another's session, background-save notes, or trajectories.
|
|
226
|
+
- Hosts that only connect through OAuth (claude.ai connectors, ChatGPT) need an
|
|
227
|
+
authorization server; set `EVEROS_MCP_AUTHORIZATION_SERVER` once one exists.
|
|
228
|
+
|
|
229
|
+
</details>
|
|
230
|
+
|
|
231
|
+
## Development
|
|
232
|
+
|
|
233
|
+
```bash
|
|
234
|
+
uv sync --dev
|
|
235
|
+
uv run ruff check . && uv run pytest # offline: wire contract, tools, guard
|
|
236
|
+
EVEROS_API_KEY=... EVEROS_USER_ID=... python scripts/smoke_test.py # live e2e
|
|
237
|
+
```
|
|
238
|
+
|
|
239
|
+
<details>
|
|
240
|
+
<summary><b>Releasing</b></summary>
|
|
241
|
+
|
|
242
|
+
<br>
|
|
243
|
+
|
|
244
|
+
Bump `version` in `pyproject.toml` and `__version__` in `src/everos_mcp/__init__.py`,
|
|
245
|
+
merge, then push a matching tag:
|
|
246
|
+
|
|
247
|
+
```bash
|
|
248
|
+
git tag v0.1.0 && git push origin v0.1.0
|
|
249
|
+
```
|
|
250
|
+
|
|
251
|
+
`.github/workflows/release.yml` tests, builds and smoke-tests the wheel, waits for
|
|
252
|
+
approval on the `release` environment, publishes to PyPI through Trusted Publishing (no
|
|
253
|
+
stored token), and drafts the GitHub Release.
|
|
254
|
+
|
|
255
|
+
</details>
|
|
256
|
+
|
|
257
|
+
<p align="right"><a href="#readme-top">back to top</a></p>
|
|
258
|
+
|
|
259
|
+
## EverMind Ecosystem
|
|
260
|
+
|
|
261
|
+
EverMind connects memory research, production-ready products, and practical
|
|
262
|
+
integrations into one open-source ecosystem.
|
|
263
|
+
|
|
264
|
+
<table>
|
|
265
|
+
<tr>
|
|
266
|
+
<th colspan="2">Products</th>
|
|
267
|
+
</tr>
|
|
268
|
+
<tr>
|
|
269
|
+
<td><strong><a href="https://github.com/EverMind-AI/EverOS">EverOS</a></strong></td>
|
|
270
|
+
<td>A local-first, Markdown-native long-term memory runtime for agents and users.</td>
|
|
271
|
+
</tr>
|
|
272
|
+
<tr>
|
|
273
|
+
<td><strong><a href="https://github.com/EverMind-AI/Raven">Raven</a></strong></td>
|
|
274
|
+
<td>A memory-first, self-improving agent harness with proactivity, context control, and skill evolution.</td>
|
|
275
|
+
</tr>
|
|
276
|
+
<tr>
|
|
277
|
+
<td><strong><a href="https://github.com/EverMind-AI/EverMe">EverMe (CLI)</a></strong></td>
|
|
278
|
+
<td>A CLI and agent plugin suite for cross-device, cross-agent personal memory.</td>
|
|
279
|
+
</tr>
|
|
280
|
+
<tr>
|
|
281
|
+
<th colspan="2">Research & Evaluation</th>
|
|
282
|
+
</tr>
|
|
283
|
+
<tr>
|
|
284
|
+
<td><strong><a href="https://github.com/EverMind-AI/SkillCorpus">SkillCorpus</a></strong></td>
|
|
285
|
+
<td>Curated, retrieval-ready agent skill corpora with retrieval and evaluation tooling.</td>
|
|
286
|
+
</tr>
|
|
287
|
+
<tr>
|
|
288
|
+
<td><strong><a href="https://github.com/EverMind-AI/EverAlgo">EverAlgo</a></strong></td>
|
|
289
|
+
<td>Stateless extraction, ranking, parsing, and memory operators that power EverOS.</td>
|
|
290
|
+
</tr>
|
|
291
|
+
<tr>
|
|
292
|
+
<td><strong><a href="https://github.com/EverMind-AI/HyperMem">HyperMem</a></strong></td>
|
|
293
|
+
<td>Hypergraph-based hierarchical memory for coarse-to-fine long-term conversation retrieval.</td>
|
|
294
|
+
</tr>
|
|
295
|
+
<tr>
|
|
296
|
+
<td><strong><a href="https://github.com/EverMind-AI/MSA">MSA</a></strong></td>
|
|
297
|
+
<td>Memory Sparse Attention for scalable latent memory and 100M-token contexts.</td>
|
|
298
|
+
</tr>
|
|
299
|
+
<tr>
|
|
300
|
+
<td><strong><a href="https://github.com/EverMind-AI/EverMemBench">EverMemBench</a></strong></td>
|
|
301
|
+
<td>Evaluation of factual recall, applied reasoning, and personalized generalization in memory systems.</td>
|
|
302
|
+
</tr>
|
|
303
|
+
<tr>
|
|
304
|
+
<td><strong><a href="https://github.com/EverMind-AI/EvoAgentBench">EvoAgentBench</a></strong></td>
|
|
305
|
+
<td>Longitudinal evaluation of agent self-evolution, transfer efficiency, error avoidance, and skill use.</td>
|
|
306
|
+
</tr>
|
|
307
|
+
<tr>
|
|
308
|
+
<th colspan="2"><a href="https://github.com/EverMind-AI/plugins">Integrations</a></th>
|
|
309
|
+
</tr>
|
|
310
|
+
<tr>
|
|
311
|
+
<td><strong><a href="https://docs.openclaw.ai">OpenClaw</a></strong></td>
|
|
312
|
+
<td><a href="https://github.com/EverMind-AI/plugins/tree/main/openclaw">OpenClaw plugin</a> for automatic recall, capture, and session-memory lifecycle management.</td>
|
|
313
|
+
</tr>
|
|
314
|
+
<tr>
|
|
315
|
+
<td><strong><a href="https://github.com/NousResearch/hermes-agent">Hermes Agent</a></strong></td>
|
|
316
|
+
<td><a href="https://github.com/EverMind-AI/plugins/tree/main/hermes">Hermes plugin</a> for persistent memory across Hermes sessions.</td>
|
|
317
|
+
</tr>
|
|
318
|
+
<tr>
|
|
319
|
+
<td><strong><a href="https://github.com/deepseek-ai/DeepSeek-Harness">DeepSeek Harness</a></strong></td>
|
|
320
|
+
<td><a href="https://github.com/EverMind-AI/plugins/tree/main/dsh">DSH plugin</a> for memory-aware DeepSeek Harness agents.</td>
|
|
321
|
+
</tr>
|
|
322
|
+
<tr>
|
|
323
|
+
<td><strong><a href="https://dify.ai">Dify</a></strong></td>
|
|
324
|
+
<td><a href="https://github.com/EverMind-AI/plugins/tree/main/dify">Self-hosted</a> and <a href="https://github.com/EverMind-AI/plugins/tree/main/dify_cloud">cloud</a> tools for explicit memory search and storage in workflows and agents.</td>
|
|
325
|
+
</tr>
|
|
326
|
+
<tr>
|
|
327
|
+
<td><strong><a href="https://github.com/EverMind-AI/EverOS-MCP">MCP</a></strong></td>
|
|
328
|
+
<td>This server: EverOS memory for Claude Code, Claude Desktop, Cursor, Codex, and any MCP client.</td>
|
|
329
|
+
</tr>
|
|
330
|
+
</table>
|
|
331
|
+
|
|
332
|
+
Together, these projects form EverMind's research-to-runtime stack: methods
|
|
333
|
+
and benchmarks become reusable memory infrastructure, products, and agent
|
|
334
|
+
integrations.
|
|
335
|
+
|
|
336
|
+
## License
|
|
337
|
+
|
|
338
|
+
[MIT](https://github.com/EverMind-AI/EverOS-MCP/blob/main/LICENSE)
|