Skip to content

feat(memory): add TypeScript MCP server alongside Python version - #80

Merged
Zhiyue-Wang merged 8 commits into
huaweicloud:mainfrom
neverland-lhy:feat/ts-memory-mcp
Oct 24, 2026
Merged

Zhiyue-Wang merged 8 commits into
huaweicloud:mainfrom
neverland-lhy:feat/ts-memory-mcp

Conversation

@neverland-lhy

@neverland-lhy neverland-lhy commented Oct 24, 2026 •

Copy link
Copy Markdown
Contributor

Summary

Adds a TypeScript implementation of the AgentArts Memory MCP server at toolkit/plugins/memory/mcp/typescript/, alongside the existing Python server (mcp/server.py). It currently exposes a single tool, search_memories.

Motivation

The Python server depends on the agentarts-sdk package (pulling in mcp, requests, etc.), which is heavy for environments that only need the MCP server. The TypeScript version has zero runtime dependencies: it calls the AgentArts Memory data-plane REST API directly and builds to a single bundled file (dist/index.mjs, ~740KB) that runs anywhere with Node >= 18 — no npm, no Python.

What's included

  • search_memories(query, strategy_type?, top_k=5, min_score=0.7, start_time?, end_time?) — semantic search with optional memory-type and time-range filters, read-only by design (writing stays with the platform hooks/plugins). user_id is resolved server-side from the environment, never a model-controlled parameter.
  • Direct data-plane REST integration — the same endpoints the .mjs hook scripts use (_shared.mjs), with no Python SDK.
  • npm run build typechecks and bundles via esbuild into a single zero-dependency dist/index.mjs; all npm deps are build-time only.
  • End-to-end test suite (npm test, node:test against a mock data plane, zero test dependencies) asserting MCP protocol behavior and REST wire-format parity with the Python server.
  • pyproject.toml: exclude mcp/typescript (and node_modules) from wheel/sdist — no Python code references the directory, and dist/ is a gitignored build artifact, so shipping it would make wheel contents depend on the packaging machine's state (without the exclusion a locally-built wheel picks up 24MB / 4264 node_modules files).

Testing

  • npm test — 8/8 end-to-end assertions against a mock data plane
  • Verified against the real data plane (cn-southwest-2): search_memories returns live data
  • uv build --no-cache — wheel and sdist contain no mcp/typescript and no node_modules files

- Read-only recall MCP server (search_memories / list_memories /
  search_summary) at toolkit/plugins/memory/mcp/typescript/, calling
  the AgentArts Memory data-plane REST API directly (no Python SDK
  dependency)
- Bundles to a single zero-dependency dist/index.mjs via esbuild
  (Node >= 18 runtime only)
- End-to-end test suite (node:test, no test deps) against a mock data
  plane, asserting MCP protocol behavior and REST wire-format parity
  with the Python server
- Exclude the TS dir and node_modules from wheel/sdist: no Python code
  references it, and dist/ is a gitignored build artifact
list_memories and search_summary are not used yet — drop them along
with the list-endpoint client path and their tests. Restorable from
history when needed.
Add strategy_type, start_time and end_time passthrough (renaming
num/threshold to top_k/min_score to match the backend filter).
Optional filters are omitted from the request body when unset,
mirroring the Python SDK's MemorySearchFilter.to_dict().
The OpenCode/Claude Code/Codex registration snippets were dropped during
an earlier README restructure (they briefly lived in examples/, which
was then removed). Restore them and flag the AGENTARTS_MEMORY_USER_ID
consistency requirement: a mismatch with the writing side makes search
silently return empty results.
- Remove unused DEFAULT_LIST_LIMIT and isConfigured() from config.ts
- Mention the optional filters (and backend strategy_type validation)
  in the tool description
- Fix stale num/threshold wording in a test comment
- README: correct bundle size (~750KB), document that invalid
  strategy_type values are rejected by the backend
- package.json: description now says 'a read-only recall tool'
Probed the live backend: the search filter accepts semantic, episodic,
user_preference, summary, procedural and event; ~40 other candidate
values are rejected with 'Malformed request body'. The enum has no
public documentation, so the parameter stays a free string with the
verified values listed in the tool description and README instead of
a hardcoded zod enum.
@codecov-commenter

Copy link
Copy Markdown

⚠️ Please install the 'codecov app svg image' to ensure uploads and comments are reliably processed by Codecov.

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 59.41%. Comparing base (9d62fce) to head (f17c6d0).
⚠️ Report is 2 commits behind head on main.
❗ Your organization needs to install the Codecov GitHub app to enable full functionality.

Additional details and impacted files
@@           Coverage Diff           @@
##             main      #80   +/-   ##
=======================================
  Coverage   59.41%   59.41%           
=======================================
  Files         115      115           
  Lines       10570    10570           
  Branches     1695     1695           
=======================================
  Hits         6280     6280           
  Misses       3752     3752           
  Partials      538      538           

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:
  • ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

@Zhiyue-Wang
Zhiyue-Wang merged commit fd1da64 into huaweicloud:main Oct 24, 2026
6 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants