records-mcp 0.1.0__tar.gz

records_mcp-0.1.0/.gitignore

@@ -0,0 +1,112 @@
+# Project-specific
+.worktrees/
+.worktree/
+.assets
+.docs
+.env
+.web
+.orion
+*.zip
+
+# Claude / AI assistant artifacts
+.superpowers/
+docs/superpowers/
+docs/plans/
+
+# webui (monorepo frontend)
+webui/node_modules/
+webui/dist/
+webui/coverage/
+webui/.vite/
+webui/public/brand/
+*.tsbuildinfo
+
+# WhatsApp bridge frontend/backend helper
+bridge/node_modules/
+bridge/dist/
+
+# Python bytecode & caches
+*.pyc
+*.pyo
+*.pyd
+*.pyw
+*.pyz
+__pycache__/
+*.egg-info/
+*.egg
+.venv/
+venv/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.pytype/
+.dmypy.json
+dmypy.json
+.tox/
+.nox/
+.hypothesis/
+
+# Build & packaging
+dist/
+dist-build-*/
+build/
+installer/tools/
+*.manifest
+*.spec
+!Nanobot.spec
+pip-wheel-metadata/
+share/python-wheels/
+
+# Test & coverage
+.coverage
+.coverage.*
+htmlcov/
+coverage.xml
+*.cover
+
+# Lock files (project policy)
+poetry.lock
+uv.lock
+
+# Jupyter
+.ipynb_checkpoints/
+
+# macOS
+.DS_Store
+.AppleDouble
+.LSOverride
+
+# Windows
+Thumbs.db
+ehthumbs.db
+Desktop.ini
+
+# Linux
+.directory
+
+# Editors & IDEs (local workspace / user settings)
+.vscode/
+.cursor/
+.idea/
+.fleet/
+*.code-workspace
+*.sublime-project
+*.sublime-workspace
+*.swp
+*.swo
+*~
+nano.*.save
+
+# Environment & secrets (keep examples tracked if needed)
+.env.*
+!.env.example
+
+# Logs & temp
+*.log
+logs/
+tmp/
+temp/
+*.tmp
+
+# Mini Harness demo outputs（运行产物，不提交）
+demo_outputs/

records_mcp-0.1.0/LICENSE

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

records_mcp-0.1.0/PKG-INFO

@@ -0,0 +1,109 @@
+Metadata-Version: 2.4
+Name: records-mcp
+Version: 0.1.0
+Summary: SQLite CRUD MCP server for teaching — exposes records database via MCP protocol
+Author: Nanobot Team
+License: MIT
+License-File: LICENSE
+Keywords: mcp,records,sqlite,teaching
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Requires-Python: >=3.11
+Requires-Dist: mcp>=1.0.0
+Description-Content-Type: text/markdown
+
+# records-mcp
+
+SQLite CRUD MCP server for teaching. Exposes a records database via the MCP protocol.
+
+## Tools
+
+| Tool | Description |
+|---|---|
+| `get_database_overview` | Record counts, status distribution, models, devices, and time range |
+| `search_records` | Search records with optional filters |
+| `get_record` | Get one record by ID |
+| `create_record` | Create a new record |
+| `update_record` | Update an existing record |
+| `delete_record` | Delete a record |
+
+## Usage
+
+```bash
+# stdio mode (default, for MCP client)
+uvx records-mcp --db records.db --transport stdio
+
+# SSE mode (network server)
+uvx records-mcp --db records.db --transport sse --host 0.0.0.0 --port 8766
+
+# streamable-http mode
+uvx records-mcp --db records.db --transport streamable-http --host 0.0.0.0 --port 8766
+```
+
+## mcp_servers.json
+
+```json
+{
+  "mcpServers": {
+    "records": {
+      "enabled": true,
+      "type": "stdio",
+      "command": "uvx",
+      "args": ["records-mcp", "--db", "records.db", "--transport", "stdio"]
+    }
+  }
+}
+```
+
+## 发布与更新版本
+
+> PyPI **不允许重复上传同一版本号**：传过的版本号（如 `0.1.0`）被永久占用，传错或想改代码只能 bump 到新版本号，不能覆盖。所以每次发布前先改版本号。
+
+### 一次性配置
+
+1. 账号开启 **2FA**（认证器 App）——PyPI 强制：没开 2FA 的账号**禁止上传**，会报 `403 Invalid API Token: current user does not match user restriction`。
+2. 在 https://pypi.org/manage/account/token/ 建一个 **API token**，scope 选 `Entire account`。token 只显示一次，记好。
+3.（可选）把凭证写进 `~/.pypirc`，省得每次输：
+
+   ```ini
+   [pypi]
+   username = __token__
+   password = pypi-你的token
+   ```
+
+   > 别把 `.pypirc` 提交进 git。
+
+### 发新版本流程
+
+```bash
+# 1. 改版本号：编辑 pyproject.toml，version = "0.1.0" → 例如 "0.1.1"
+#    （语义化版本：修 bug → 0.1.x，加功能 → 0.x.0，不兼容改动 → x.0.0）
+
+# 2. 清掉旧产物，避免把旧 wheel / 旧 sdist 一起传上去
+rm -rf dist build *.egg-info
+
+# 3. 构建 wheel + sdist
+python -m build          # 或 uv build
+
+# 4. 检查 metadata 没问题（期望两条 PASSED）
+twine check dist/*
+
+# 5.（可选）先发 TestPyPI 验证一遍，确认无误再发真的
+twine upload --repository-url https://test.pypi.org/legacy/ dist/*
+
+# 6. 发到真 PyPI
+twine upload dist/*      # 或：uv publish --token <token> dist/*
+
+# 7. 验证：用全新环境拉一遍，确认入口命令可用
+uvx records-mcp --help
+```
+
+### 常见坑
+
+- **版本号不可重用**：`0.1.0` 传过一次就锁死，删了项目也不能再用这个号传；改代码必须 bump 版本号。
+- **没开 2FA 传不上去**：报 `403 ... current user does not match user restriction`，去 Account settings 把 2FA（认证器 App）开了再传——只生成恢复码还不够。
+- **token 泄露立刻撤**：在 token 页 Remove 旧 token、重建一个。

records_mcp-0.1.0/README.md

@@ -0,0 +1,91 @@
+# records-mcp
+
+SQLite CRUD MCP server for teaching. Exposes a records database via the MCP protocol.
+
+## Tools
+
+| Tool | Description |
+|---|---|
+| `get_database_overview` | Record counts, status distribution, models, devices, and time range |
+| `search_records` | Search records with optional filters |
+| `get_record` | Get one record by ID |
+| `create_record` | Create a new record |
+| `update_record` | Update an existing record |
+| `delete_record` | Delete a record |
+
+## Usage
+
+```bash
+# stdio mode (default, for MCP client)
+uvx records-mcp --db records.db --transport stdio
+
+# SSE mode (network server)
+uvx records-mcp --db records.db --transport sse --host 0.0.0.0 --port 8766
+
+# streamable-http mode
+uvx records-mcp --db records.db --transport streamable-http --host 0.0.0.0 --port 8766
+```
+
+## mcp_servers.json
+
+```json
+{
+  "mcpServers": {
+    "records": {
+      "enabled": true,
+      "type": "stdio",
+      "command": "uvx",
+      "args": ["records-mcp", "--db", "records.db", "--transport", "stdio"]
+    }
+  }
+}
+```
+
+## 发布与更新版本
+
+> PyPI **不允许重复上传同一版本号**：传过的版本号（如 `0.1.0`）被永久占用，传错或想改代码只能 bump 到新版本号，不能覆盖。所以每次发布前先改版本号。
+
+### 一次性配置
+
+1. 账号开启 **2FA**（认证器 App）——PyPI 强制：没开 2FA 的账号**禁止上传**，会报 `403 Invalid API Token: current user does not match user restriction`。
+2. 在 https://pypi.org/manage/account/token/ 建一个 **API token**，scope 选 `Entire account`。token 只显示一次，记好。
+3.（可选）把凭证写进 `~/.pypirc`，省得每次输：
+
+   ```ini
+   [pypi]
+   username = __token__
+   password = pypi-你的token
+   ```
+
+   > 别把 `.pypirc` 提交进 git。
+
+### 发新版本流程
+
+```bash
+# 1. 改版本号：编辑 pyproject.toml，version = "0.1.0" → 例如 "0.1.1"
+#    （语义化版本：修 bug → 0.1.x，加功能 → 0.x.0，不兼容改动 → x.0.0）
+
+# 2. 清掉旧产物，避免把旧 wheel / 旧 sdist 一起传上去
+rm -rf dist build *.egg-info
+
+# 3. 构建 wheel + sdist
+python -m build          # 或 uv build
+
+# 4. 检查 metadata 没问题（期望两条 PASSED）
+twine check dist/*
+
+# 5.（可选）先发 TestPyPI 验证一遍，确认无误再发真的
+twine upload --repository-url https://test.pypi.org/legacy/ dist/*
+
+# 6. 发到真 PyPI
+twine upload dist/*      # 或：uv publish --token <token> dist/*
+
+# 7. 验证：用全新环境拉一遍，确认入口命令可用
+uvx records-mcp --help
+```
+
+### 常见坑
+
+- **版本号不可重用**：`0.1.0` 传过一次就锁死，删了项目也不能再用这个号传；改代码必须 bump 版本号。
+- **没开 2FA 传不上去**：报 `403 ... current user does not match user restriction`，去 Account settings 把 2FA（认证器 App）开了再传——只生成恢复码还不够。
+- **token 泄露立刻撤**：在 token 页 Remove 旧 token、重建一个。

records_mcp-0.1.0/pyproject.toml

@@ -0,0 +1,32 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "records-mcp"
+version = "0.1.0"
+description = "SQLite CRUD MCP server for teaching — exposes records database via MCP protocol"
+readme = "README.md"
+license = { text = "MIT" }
+requires-python = ">=3.11"
+authors = [
+    { name = "Nanobot Team" }
+]
+keywords = ["mcp", "sqlite", "records", "teaching"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+]
+dependencies = [
+    "mcp>=1.0.0",
+]
+
+[project.scripts]
+records-mcp = "records_mcp_server:main"
+
+[tool.hatch.build.targets.wheel]
+force-include = { "records_mcp_server.py" = "records_mcp_server.py" }

records_mcp-0.1.0/records_mcp_server.py

@@ -0,0 +1,291 @@
+#!/usr/bin/env python3
+"""SQLite CRUD MCP server used by the mini Harness lessons."""
+
+import argparse
+import json
+import os
+import sqlite3
+import sys
+from datetime import datetime
+from pathlib import Path
+from typing import Any
+
+from mcp.server.fastmcp import FastMCP
+
+
+def _connect_database(db_path: Path) -> sqlite3.Connection:
+    """Open the teaching database used by both read and write tools."""
+    connection = sqlite3.connect(db_path)
+    connection.row_factory = sqlite3.Row
+    return connection
+
+
+def _json(data: Any) -> str:
+    return json.dumps(data, ensure_ascii=False, indent=2)
+
+
+def _log(event: str, **details: Any) -> None:
+    """Write teaching logs to stderr; stdout is reserved for MCP stdio messages."""
+    suffix = " ".join(f"{key}={value!r}" for key, value in details.items())
+    print(f"[records-mcp] {event} {suffix}".rstrip(), file=sys.stderr, flush=True)
+
+
+def create_server(db_path: Path, host: str, port: int) -> FastMCP:
+    """Create a server whose tools are bound to one SQLite database."""
+    mcp = FastMCP(
+        "records-database",
+        instructions="Create, read, update, and delete records in the teaching dataset.",
+        host=host,
+        port=port,
+    )
+
+    @mcp.tool()
+    def get_database_overview() -> str:
+        """Return record counts, status distribution, models, devices, and time range."""
+        _log("call", tool="get_database_overview")
+        with _connect_database(db_path) as connection:
+            summary = connection.execute(
+                """
+                SELECT
+                    COUNT(*) AS total_records,
+                    COUNT(DISTINCT deviceSN) AS device_count,
+                    COUNT(DISTINCT modelName) AS model_count,
+                    MIN(captureTime) AS earliest_capture,
+                    MAX(captureTime) AS latest_capture
+                FROM records
+                """
+            ).fetchone()
+            statuses = connection.execute(
+                "SELECT status, COUNT(*) AS count FROM records GROUP BY status ORDER BY count DESC"
+            ).fetchall()
+            models = connection.execute(
+                "SELECT modelName, COUNT(*) AS count FROM records "
+                "GROUP BY modelName ORDER BY count DESC, modelName"
+            ).fetchall()
+        _log("result", tool="get_database_overview", total=summary["total_records"])
+        return _json(
+            {
+                "database": str(db_path),
+                "summary": dict(summary),
+                "status_counts": [dict(row) for row in statuses],
+                "model_counts": [dict(row) for row in models],
+            }
+        )
+
+    @mcp.tool()
+    def search_records(
+        device_sn: str | None = None,
+        model_name: str | None = None,
+        status: str | None = None,
+        start_time: str | None = None,
+        end_time: str | None = None,
+        limit: int = 20,
+    ) -> str:
+        """Search records with optional exact filters and an inclusive capture-time range."""
+        _log(
+            "call",
+            tool="search_records",
+            device_sn=device_sn,
+            model_name=model_name,
+            status=status,
+            limit=limit,
+        )
+        if not 1 <= limit <= 100:
+            raise ValueError("limit must be between 1 and 100")
+
+        clauses: list[str] = []
+        parameters: list[Any] = []
+        filters = (
+            ("deviceSN = ?", device_sn),
+            ("modelName = ?", model_name),
+            ("status = ?", status),
+            ("captureTime >= ?", start_time),
+            ("captureTime <= ?", end_time),
+        )
+        for clause, value in filters:
+            if value is not None:
+                clauses.append(clause)
+                parameters.append(value)
+
+        where = f" WHERE {' AND '.join(clauses)}" if clauses else ""
+        sql = (
+            "SELECT id, deviceSN, modelName, modelVersion, captureTime, imageUrl, status, "
+            "error, orig_path, draw_path, updated_at FROM records"
+            f"{where} ORDER BY captureTime DESC, id DESC LIMIT ?"
+        )
+        parameters.append(limit)
+        with _connect_database(db_path) as connection:
+            rows = connection.execute(sql, parameters).fetchall()
+        _log("result", tool="search_records", count=len(rows))
+        return _json(
+            {
+                "count": len(rows),
+                "limit": limit,
+                "records": [dict(row) for row in rows],
+            }
+        )
+
+    @mcp.tool()
+    def get_record(record_id: int) -> str:
+        """Return one record by its integer primary key."""
+        _log("call", tool="get_record", record_id=record_id)
+        with _connect_database(db_path) as connection:
+            row = connection.execute(
+                "SELECT * FROM records WHERE id = ?", (record_id,)
+            ).fetchone()
+        if row is None:
+            _log("result", tool="get_record", record_id=record_id, found=False)
+            return _json({"found": False, "record": None})
+        _log("result", tool="get_record", record_id=record_id, found=True)
+        return _json({"found": True, "record": dict(row)})
+
+    @mcp.tool()
+    def create_record(
+        device_sn: str,
+        model_name: str,
+        model_version: str = "",
+        capture_time: str = "",
+        image_url: str = "",
+        status: str = "ignored",
+        error: str = "",
+        orig_path: str = "",
+        draw_path: str = "",
+    ) -> str:
+        """Create a record and return it. Production code should validate values and authorize writes."""
+        _log(
+            "call",
+            tool="create_record",
+            device_sn=device_sn,
+            model_name=model_name,
+            status=status,
+        )
+        now = datetime.now().isoformat(sep=" ", timespec="seconds")
+        with _connect_database(db_path) as connection:
+            cursor = connection.execute(
+                """
+                INSERT INTO records (
+                    deviceSN, modelName, modelVersion, captureTime, imageUrl,
+                    status, error, orig_path, draw_path, updated_at
+                ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+                """,
+                (
+                    device_sn,
+                    model_name,
+                    model_version,
+                    capture_time or now,
+                    image_url,
+                    status,
+                    error,
+                    orig_path,
+                    draw_path,
+                    now,
+                ),
+            )
+            row = connection.execute(
+                "SELECT * FROM records WHERE id = ?", (cursor.lastrowid,)
+            ).fetchone()
+        _log("result", tool="create_record", record_id=cursor.lastrowid)
+        return _json({"created": dict(row)})
+
+    @mcp.tool()
+    def update_record(
+        record_id: int,
+        device_sn: str | None = None,
+        model_name: str | None = None,
+        model_version: str | None = None,
+        capture_time: str | None = None,
+        image_url: str | None = None,
+        status: str | None = None,
+        error: str | None = None,
+        orig_path: str | None = None,
+        draw_path: str | None = None,
+    ) -> str:
+        """Update supplied fields. Production code should add authorization, validation, and concurrency checks."""
+        values = {
+            "deviceSN": device_sn,
+            "modelName": model_name,
+            "modelVersion": model_version,
+            "captureTime": capture_time,
+            "imageUrl": image_url,
+            "status": status,
+            "error": error,
+            "orig_path": orig_path,
+            "draw_path": draw_path,
+        }
+        changes = {column: value for column, value in values.items() if value is not None}
+        _log("call", tool="update_record", record_id=record_id, fields=list(changes))
+        if not changes:
+            _log("result", tool="update_record", record_id=record_id, updated=False)
+            return _json({"error": "no fields were supplied for update"})
+
+        with _connect_database(db_path) as connection:
+            before = connection.execute(
+                "SELECT * FROM records WHERE id = ?", (record_id,)
+            ).fetchone()
+            if before is None:
+                _log("result", tool="update_record", record_id=record_id, found=False)
+                return _json({"error": f"record {record_id} was not found"})
+
+            changes["updated_at"] = datetime.now().isoformat(sep=" ", timespec="seconds")
+            assignments = ", ".join(f"{column} = ?" for column in changes)
+            connection.execute(
+                f"UPDATE records SET {assignments} WHERE id = ?",
+                [*changes.values(), record_id],
+            )
+            after = connection.execute(
+                "SELECT * FROM records WHERE id = ?", (record_id,)
+            ).fetchone()
+        _log("result", tool="update_record", record_id=record_id, updated=True)
+        return _json({"before": dict(before), "after": dict(after)})
+
+    @mcp.tool()
+    def delete_record(record_id: int) -> str:
+        """Permanently delete a record. Production code should prefer authorization and soft deletion."""
+        _log("call", tool="delete_record", record_id=record_id)
+        with _connect_database(db_path) as connection:
+            row = connection.execute(
+                "SELECT * FROM records WHERE id = ?", (record_id,)
+            ).fetchone()
+            if row is None:
+                _log("result", tool="delete_record", record_id=record_id, found=False)
+                return _json({"error": f"record {record_id} was not found"})
+            connection.execute("DELETE FROM records WHERE id = ?", (record_id,))
+        _log("result", tool="delete_record", record_id=record_id, deleted=True)
+        return _json({"deleted": dict(row)})
+
+    return mcp
+
+
+def _parse_args() -> argparse.Namespace:
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument(
+        "--db",
+        type=Path,
+        default=os.getenv("RECORDS_DB_PATH"),
+        help="path to records.db (or set RECORDS_DB_PATH)",
+    )
+    parser.add_argument(
+        "--transport",
+        choices=("stdio", "sse", "streamable-http"),
+        default="stdio",
+    )
+    parser.add_argument("--host", default="127.0.0.1")
+    parser.add_argument("--port", type=int, default=8766)
+    return parser.parse_args()
+
+
+def main() -> None:
+    args = _parse_args()
+    if args.db is None:
+        raise SystemExit("--db or RECORDS_DB_PATH is required")
+    db_path = args.db.expanduser().resolve()
+    if not db_path.is_file():
+        raise SystemExit(f"database not found: {db_path}")
+    _log("starting", transport=args.transport, database=str(db_path))
+    if args.transport == "stdio":
+        _log("waiting", message="stdio server is waiting for MCP JSON-RPC on stdin")
+    create_server(db_path, args.host, args.port).run(transport=args.transport)
+
+
+if __name__ == "__main__":
+    main()