timem-mcp 0.1.0__tar.gz

timem_mcp-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,50 @@
+name: Publish to PyPI
+
+on:
+  push:
+    tags:
+      - "v*" # Auto-trigger when pushing a tag starting with v
+  release:
+    types: [published]
+  workflow_dispatch:
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      id-token: write # For PyPI trusted publishing
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+
+      - name: Install build dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install build
+
+      - name: Clean dist directory before build
+        run: |
+          # Clean dist directory to ensure only current build files are included
+          rm -rf dist/*
+          echo "Cleaned dist directory"
+
+      - name: Build package
+        run: |
+          python -m build
+
+      - name: List built packages
+        run: |
+          echo "Built packages:"
+          ls -la dist/
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          packages-dir: dist/

timem_mcp-0.1.0/.gitignore

@@ -0,0 +1,77 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+pip-wheel-metadata/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py,cover
+.hypothesis/
+.pytest_cache/
+
+# Translations
+*.mo
+*.pot
+
+# Environments
+.env
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# IDEs
+.vscode/
+.idea/
+*.swp
+*.swo
+*~
+
+# OS
+.DS_Store
+Thumbs.db
+
+# MCP Inspector
+.mcp-inspector/

timem_mcp-0.1.0/CLAUDE.md

@@ -0,0 +1,79 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Project Overview
+
+TiMEM MCP Server is a Model Context Protocol (MCP) server that provides memory management tools for TiMEM Engine. The project is built using FastMCP framework and communicates with MCP clients like Claude Desktop via stdio transport.
+
+## Common Commands
+
+### Development
+```bash
+# Install in development mode
+pip install -e .
+
+# Run directly (using Python module)
+python -m timem_mcp
+
+# Run using uvx (recommended)
+uvx timem-mcp
+
+# Debug with MCP Inspector
+npx @modelcontextprotocol/inspector uvx --from <your-local-path> timem-mcp -e TiMEM_API_HOST=http://localhost:8000 -e TiMEM_API_KEY=<your-api-key> -e TiMEM_USER_ID=<your-user-id>
+```
+
+### Build and Publish
+```bash
+# Build package
+python -m build
+
+# Check package
+twine check dist/*
+```
+
+### Configuration Requirements
+The following environment variables are required to run the service:
+- `TiMEM_API_KEY`: TiMEM Engine API Key
+- `TiMEM_USER_ID`: User ID
+
+Optional configuration:
+- `TiMEM_API_HOST`: API endpoint (defaults to `https://api.timem.cloud`)
+
+## Code Architecture
+
+```
+timem_mcp/
+├── __init__.py      # Exports main entry point and version
+├── __main__.py      # Entry: validate config → start MCP server (stdio)
+├── server.py        # MCP core: FastMCP instance + 3 tool definitions
+├── client.py        # HTTP client: async calls to TiMEM Engine API
+└── config.py        # Config management: env var reading (supports TiMEM_*/TIMEM_* prefixes)
+```
+
+### Execution Flow
+1. `__main__.py:main()` → validate env vars → call `mcp.run(transport="stdio")`
+2. `server.py` uses FastMCP decorators to register tool functions
+3. Tool functions call TiMEM Engine API via `client.py:call_api()`
+4. API paths retrieved from `config.py:Config` constants: `MEMORY_CREATE_PATH` / `MEMORY_QUERY_PATH`
+5. Configuration retrieved from `config.py` getters: `get_api_key()` / `get_user_id()` / `get_base_url()`
+
+### MCP Tools
+| Tool | Purpose | API Endpoint |
+|------|---------|--------------|
+| `create_memory` | Create memories from conversation history | POST `/api/v1/memory/` |
+| `search_memories` | Search stored memories | GET `/api/v1/memory/query` |
+| `ready` | Health check | - |
+
+## Key Design Points
+
+- **Environment variable prefix priority**: `TiMEM_*` > `TIMEM_*` (implemented in `config.py:Config._get_env`)
+- **API authentication**: Via `X-API-Key` request header (`client.py:call_api`)
+- **Response format handling**: `create_memory` wraps list responses as `{"status": "success", "memories": [...], "count": n}` (`server.py:70-72`)
+- **Transport mode**: MCP standard requires `stdio` transport, not HTTP
+
+## Notes
+
+- Project uses `pyproject.toml` for dependency management, not `requirements.txt`
+- `timem_mcp_service.py` in root directory is a legacy file; use code in `timem_mcp/` package
+- PyPI package name is `timem-mcp`, but Python import name is `timem_mcp` (follows Python convention)

timem_mcp-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 TiMEM Team
+
+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.

timem_mcp-0.1.0/PKG-INFO

@@ -0,0 +1,145 @@
+Metadata-Version: 2.4
+Name: timem-mcp
+Version: 0.1.0
+Summary: TiMEM MCP Server - Model Context Protocol server for TiMEM Engine
+Project-URL: Homepage, https://github.com/timem-cloud/timem-mcp
+Project-URL: Documentation, https://docs.timem.cloud
+Project-URL: Repository, https://github.com/timem-cloud/timem-mcp
+Author-email: TiMEM Team <contact@timem.cloud>
+License: MIT
+License-File: LICENSE
+Keywords: ai,mcp,memory,model-context-protocol,timem
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Requires-Python: >=3.8
+Requires-Dist: fastmcp>=0.1.0
+Requires-Dist: httpx>=0.24.0
+Provides-Extra: dev
+Requires-Dist: pytest-asyncio>=0.21.0; extra == 'dev'
+Requires-Dist: pytest>=7.0.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# TiMEM MCP Server
+
+[Model Context Protocol](https://modelcontextprotocol.io) server for [TiMEM Engine](https://timem.cloud), providing memory management tools for AI applications.
+
+## Installation
+
+```bash
+pip install timem-mcp
+```
+
+## Usage
+
+### With Claude Desktop
+
+Add to your Claude Desktop configuration (`claude_desktop_config.json`):
+
+```json
+{
+  "mcpServers": {
+    "TiMEM-MCP": {
+      "command": "uvx",
+      "args": ["timem-mcp"],
+      "env": {
+        "TiMEM_API_KEY": "<your-api-key>",
+        "TiMEM_API_HOST": "https://api.timem.cloud",  // optional
+        "TiMEM_USER_ID": "<your-user-id>"
+      }
+    }
+  }
+}
+```
+
+### Direct Execution
+
+```bash
+# Using uvx (recommended)
+uvx timem-mcp
+
+# Or using Python module
+python -m timem_mcp
+
+# Or directly if installed
+timem-mcp
+```
+
+## Configuration
+
+The server reads configuration from environment variables:
+
+| Variable | Required | Default | Description |
+|----------|----------|---------|-------------|
+| `TiMEM_API_KEY` | Yes | - | Your TiMEM Engine API key |
+| `TiMEM_USER_ID` | Yes | - | User identifier for memory operations |
+| `TiMEM_API_HOST` | No | `https://api.timem.cloud` | TiMEM Engine API endpoint |
+
+**Note:** Both `TiMEM_*` and `TIMEM_*` prefixes are supported. `TiMEM_*` takes priority.
+
+## Available Tools
+
+### `create_memory`
+
+Create memories from conversation history.
+
+**Parameters:**
+- `messages` (required): List of message objects with `role` and `content`
+- `session_id` (required): Session identifier
+- `expert_id` (optional): Expert ID, default "default"
+- `domain` (optional): Business domain, default "general"
+
+**Example:**
+```python
+await create_memory(
+    messages=[
+        {"role": "user", "content": "My name is John"},
+        {"role": "assistant", "content": "Hello John!"}
+    ],
+    session_id="sess_123",
+    expert_id="default",
+    domain="general"
+)
+```
+
+### `search_memories`
+
+Search and retrieve stored memories.
+
+**Parameters:**
+- `query` (optional): Search keywords
+- `layer` (optional): Memory layer (L1-L5)
+- `domain` (optional): Business domain
+- `limit` (optional): Result count, default 10
+
+**Example:**
+```python
+await search_memories(query="John", layer="L1", limit=5)
+```
+
+### `ready`
+
+Health check endpoint to verify the server is running.
+
+## Development
+
+```bash
+# Install in development mode
+pip install -e .
+
+# Run tests
+pytest
+
+# Run with MCP Inspector
+npx @modelcontextprotocol/inspector uvx --from <your-local-path> timem-mcp -e TiMEM_API_HOST=http://localhost:8000 -e TiMEM_API_KEY=<your-api-key> -e TiMEM_USER_ID=<your-user-id>
+```
+
+## License
+
+MIT License - see LICENSE file for details.

timem_mcp-0.1.0/README.md

@@ -0,0 +1,117 @@
+# TiMEM MCP Server
+
+[Model Context Protocol](https://modelcontextprotocol.io) server for [TiMEM Engine](https://timem.cloud), providing memory management tools for AI applications.
+
+## Installation
+
+```bash
+pip install timem-mcp
+```
+
+## Usage
+
+### With Claude Desktop
+
+Add to your Claude Desktop configuration (`claude_desktop_config.json`):
+
+```json
+{
+  "mcpServers": {
+    "TiMEM-MCP": {
+      "command": "uvx",
+      "args": ["timem-mcp"],
+      "env": {
+        "TiMEM_API_KEY": "<your-api-key>",
+        "TiMEM_API_HOST": "https://api.timem.cloud",  // optional
+        "TiMEM_USER_ID": "<your-user-id>"
+      }
+    }
+  }
+}
+```
+
+### Direct Execution
+
+```bash
+# Using uvx (recommended)
+uvx timem-mcp
+
+# Or using Python module
+python -m timem_mcp
+
+# Or directly if installed
+timem-mcp
+```
+
+## Configuration
+
+The server reads configuration from environment variables:
+
+| Variable | Required | Default | Description |
+|----------|----------|---------|-------------|
+| `TiMEM_API_KEY` | Yes | - | Your TiMEM Engine API key |
+| `TiMEM_USER_ID` | Yes | - | User identifier for memory operations |
+| `TiMEM_API_HOST` | No | `https://api.timem.cloud` | TiMEM Engine API endpoint |
+
+**Note:** Both `TiMEM_*` and `TIMEM_*` prefixes are supported. `TiMEM_*` takes priority.
+
+## Available Tools
+
+### `create_memory`
+
+Create memories from conversation history.
+
+**Parameters:**
+- `messages` (required): List of message objects with `role` and `content`
+- `session_id` (required): Session identifier
+- `expert_id` (optional): Expert ID, default "default"
+- `domain` (optional): Business domain, default "general"
+
+**Example:**
+```python
+await create_memory(
+    messages=[
+        {"role": "user", "content": "My name is John"},
+        {"role": "assistant", "content": "Hello John!"}
+    ],
+    session_id="sess_123",
+    expert_id="default",
+    domain="general"
+)
+```
+
+### `search_memories`
+
+Search and retrieve stored memories.
+
+**Parameters:**
+- `query` (optional): Search keywords
+- `layer` (optional): Memory layer (L1-L5)
+- `domain` (optional): Business domain
+- `limit` (optional): Result count, default 10
+
+**Example:**
+```python
+await search_memories(query="John", layer="L1", limit=5)
+```
+
+### `ready`
+
+Health check endpoint to verify the server is running.
+
+## Development
+
+```bash
+# Install in development mode
+pip install -e .
+
+# Run tests
+pytest
+
+# Run with MCP Inspector
+npx @modelcontextprotocol/inspector uvx --from <your-local-path> timem-mcp -e TiMEM_API_HOST=http://localhost:8000 -e TiMEM_API_KEY=<your-api-key> -e TiMEM_USER_ID=<your-user-id>
+```
+
+## License
+
+MIT License - see LICENSE file for details.

timem_mcp-0.1.0/pyproject.toml

@@ -0,0 +1,48 @@
+[project]
+name = "timem-mcp"
+version = "0.1.0"
+description = "TiMEM MCP Server - Model Context Protocol server for TiMEM Engine"
+readme = "README.md"
+requires-python = ">=3.8"
+license = { text = "MIT" }
+authors = [
+    { name = "TiMEM Team", email = "contact@timem.cloud" }
+]
+keywords = ["mcp", "timem", "memory", "ai", "model-context-protocol"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.8",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+]
+
+dependencies = [
+    "fastmcp>=0.1.0",
+    "httpx>=0.24.0",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=7.0.0",
+    "pytest-asyncio>=0.21.0",
+]
+
+[project.scripts]
+timem-mcp = "timem_mcp:main"
+
+[project.urls]
+Homepage = "https://github.com/timem-cloud/timem-mcp"
+Documentation = "https://docs.timem.cloud"
+Repository = "https://github.com/timem-cloud/timem-mcp"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["timem_mcp"]

timem_mcp-0.1.0/timem_mcp/__init__.py

@@ -0,0 +1,10 @@
+"""TiMEM MCP 服务包
+
+提供通过 uvx 启动的标准 MCP 服务
+"""
+
+from .__main__ import main
+
+__version__ = "0.1.0"
+
+__all__ = ["main", "__version__"]

timem_mcp-0.1.0/timem_mcp/__main__.py

@@ -0,0 +1,26 @@
+"""TiMEM MCP 服务入口点
+
+支持通过 `uvx timem-mcp` 或 `python -m timem_mcp` 启动服务
+"""
+
+import sys
+
+from .config import validate
+from .server import mcp
+
+
+def main() -> None:
+    """主入口函数"""
+    try:
+        # 验证必需的环境变量
+        validate()
+    except ValueError as e:
+        print(f"配置错误: {e}", file=sys.stderr)
+        sys.exit(1)
+
+    # 使用 stdio 传输方式启动服务（MCP 标准要求）
+    mcp.run(transport="stdio")
+
+
+if __name__ == "__main__":
+    main()

timem_mcp-0.1.0/timem_mcp/client.py

@@ -0,0 +1,51 @@
+"""TiMEM API 客户端模块
+
+提供异步 HTTP 客户端用于调用 TiMEM Engine API
+"""
+
+from typing import Any, Dict, Optional
+
+import httpx
+
+from .config import get_base_url
+
+
+async def call_api(
+    method: str,
+    path: str,
+    api_key: str,
+    json_data: Optional[Dict] = None,
+    params: Optional[Dict] = None,
+    timeout: float = 30.0,
+) -> Dict[str, Any]:
+    """通用 API 调用函数
+
+    Args:
+        method: HTTP 方法 (GET/POST)
+        path: API 路径
+        api_key: API Key
+        json_data: JSON 请求体 (POST 时使用)
+        params: URL 查询参数 (GET 时使用)
+        timeout: 超时时间
+
+    Returns:
+        API 响应数据
+
+    Raises:
+        httpx.HTTPStatusError: API 请求失败
+    """
+    url = f"{get_base_url()}{path}"
+    headers = {"X-API-Key": api_key}
+
+    async with httpx.AsyncClient() as client:
+        if method.upper() == "POST":
+            response = await client.post(
+                url, json=json_data, headers=headers, timeout=timeout
+            )
+        else:
+            response = await client.get(
+                url, params=params, headers=headers, timeout=timeout
+            )
+
+        response.raise_for_status()
+        return response.json()

timem_mcp-0.1.0/timem_mcp/config.py

@@ -0,0 +1,79 @@
+"""TiMEM MCP 配置模块
+
+从环境变量读取配置，支持 TiMEM_* 和 TIMEM_* 两种前缀。
+优先级: TiMEM_* > TIMEM_*
+"""
+
+import os
+from typing import Optional
+
+
+class Config:
+    """配置管理类"""
+
+    # 环境变量前缀
+    PREFIXES = ["TiMEM_", "TIMEM_"]
+
+    # API paths
+    MEMORY_CREATE_PATH = "/api/v1/memory/"
+    MEMORY_QUERY_PATH = "/api/v1/memory/query"
+
+    # Default API base URL
+    DEFAULT_BASE_URL = "https://api.timem.cloud"
+
+    @classmethod
+    def _get_env(cls, key: str) -> Optional[str]:
+        """获取环境变量，支持多种前缀
+
+        Args:
+            key: 配置键名（不含前缀）
+
+        Returns:
+            环境变量值，如果不存在则返回 None
+        """
+        # 按优先级尝试不同前缀
+        for prefix in cls.PREFIXES:
+            value = os.getenv(f"{prefix}{key}")
+            if value:
+                return value
+        return None
+
+    @classmethod
+    def get_api_key(cls) -> str:
+        """获取 API Key（必需）"""
+        api_key = cls._get_env("API_KEY")
+        if not api_key:
+            raise ValueError(
+                "TiMEM_API_KEY 环境变量未设置。"
+                "请在环境变量中设置 TiMEM_API_KEY 或 TIMEM_API_KEY"
+            )
+        return api_key
+
+    @classmethod
+    def get_user_id(cls) -> str:
+        """获取用户 ID（必需）"""
+        user_id = cls._get_env("USER_ID")
+        if not user_id:
+            raise ValueError(
+                "TiMEM_USER_ID 环境变量未设置。"
+                "请在环境变量中设置 TiMEM_USER_ID 或 TIMEM_USER_ID"
+            )
+        return user_id
+
+    @classmethod
+    def get_base_url(cls) -> str:
+        """获取 API 基础地址"""
+        return cls._get_env("API_HOST") or cls.DEFAULT_BASE_URL
+
+    @classmethod
+    def validate(cls) -> None:
+        """验证必需的配置项"""
+        cls.get_api_key()
+        cls.get_user_id()
+
+
+# 导出便捷访问函数
+get_api_key = Config.get_api_key
+get_user_id = Config.get_user_id
+get_base_url = Config.get_base_url
+validate = Config.validate

timem_mcp-0.1.0/timem_mcp/server.py

@@ -0,0 +1,119 @@
+"""TiMEM MCP 服务模块
+
+提供 create_memory 和 search_memories 两个核心工具
+"""
+
+from typing import Any, Dict, List, Optional
+
+from fastmcp import FastMCP
+
+from .client import call_api
+from .config import get_api_key, get_user_id, Config
+
+__version__ = "0.1.0"
+
+# 创建 MCP 服务器实例
+mcp = FastMCP("TiMEM")
+
+
+@mcp.tool()
+async def create_memory(
+    messages: List[Dict[str, str]],
+    session_id: str,
+    expert_id: str = "default",
+    domain: str = "general",
+) -> Dict[str, Any]:
+    """从对话历史创建记忆
+
+    Args:
+        messages: 对话消息列表，格式 [{"role": "user|assistant", "content": "..."}]
+        session_id: 会话ID
+        expert_id: 专家ID (默认 "default")
+        domain: 业务域 (默认 "general")
+
+    Returns:
+        创建的结果，包含 status 和 memories/data 字段
+
+    Example:
+        result = await create_memory(
+            messages=[
+                {"role": "user", "content": "你好，我叫张三"},
+                {"role": "assistant", "content": "你好张三，很高兴认识你"}
+            ],
+            session_id="sess_456",
+            expert_id="agent_001",
+            domain="customer_service"
+        )
+    """
+    # 从环境变量读取 API Key 和用户 ID
+    api_key = get_api_key()
+    user_id = get_user_id()
+
+    request_body = {
+        "user_id": user_id,
+        "expert_id": expert_id,
+        "session_id": session_id,
+        "messages": [
+            {"role": msg.get("role"), "content": msg.get("content")} for msg in messages
+        ],
+        "format": "compact",
+    }
+
+    if domain:
+        request_body["domain"] = domain
+
+    response = await call_api(
+        "POST", Config.MEMORY_CREATE_PATH, api_key, json_data=request_body, timeout=60.0
+    )
+
+    # 主服务返回的是列表格式，需要包装成字典
+    if isinstance(response, list):
+        return {"status": "success", "memories": response, "count": len(response)}
+    return response
+
+
+@mcp.tool()
+async def search_memories(
+    query: Optional[str] = None,
+    layer: Optional[str] = None,
+    domain: Optional[str] = None,
+    limit: int = 10,
+) -> Dict[str, Any]:
+    """搜索/查询记忆
+
+    Args:
+        query: 搜索关键词
+        layer: 记忆层级 L1-L5
+        domain: 业务域
+        limit: 返回数量 (默认 10)
+
+    Returns:
+        搜索结果列表
+
+    Example:
+        result = await search_memories(
+            query="张三",
+            layer="L1",
+            limit=5
+        )
+    """
+    # 从环境变量读取 API Key 和用户 ID
+    api_key = get_api_key()
+    user_id = get_user_id()
+
+    params = {"user_id": user_id, "size": limit}
+
+    if query:
+        params["keywords"] = [query]
+    if layer:
+        params["layer"] = layer
+    if domain:
+        params["domain"] = domain
+
+    return await call_api("GET", Config.MEMORY_QUERY_PATH, api_key, params=params)
+
+
+@mcp.tool()
+def ready() -> str:
+    """确认服务已就绪"""
+    return "ready"