feat: mcp-server-basti — privater stdio-MCP-Server mit 3 Tools

[Toqsick]

Baut einen lokalen MCP-Server (FastMCP v3) mit drei Tools:

• get_system_status: uptime-Subprocess
• echo_tool: passthrough (Health-Check)
• get_repo_info: git branch + commit des Server-Repos

Architektur:

• stdio-Transport, Logging nach stderr (MCP-stdio-Konflikt vermieden)
• asyncio.to_thread für subprocess (blockiert nicht den Event-Loop)
• fastmcp.ToolResult mit is_error=True für strukturierte Tool-Errors
• DEFAULT_REPO_PATH für vorhersagbare cwd-Auflösung

Toolchain:

• uv/uvx als Runtime, hatchling als Build-Backend, Python >=3.11
• Dependencies: mcp[cli]>=1.0, fastmcp>=2.0

Tests (17/17 grün):

• 10 Unit-Tests mit pytest.importorskip (kein silent skip bei Import-Bugs)
• 7 Integration-Tests via stdio_client mit asyncio.wait_for-Timeouts
• conftest.py zentralisiert server_params-Fixture

CI (GitHub Actions, ubuntu-latest, Python 3.11):

• lint: ruff auf src/
• test: uv sync --all-extras + pytest (mit env -u PYTHONPATH)
• build: uv build + Wheel-Installation + Entry-Point-Smoke-Test

Debug-Audit-Phase (4 parallele Subagenten, 7 CRITICAL + 12 HIGH behoben):

• _structured_error nutzt fastmcp.ToolResult statt mcp.types.CallToolResult
• Logging nach stderr (fd 2), niemals stdout (fd 1)
• .mcp.json nutzt ${CLAUDE_PROJECT_ROOT} statt hard-coded Pfad
• test_error_handling ohne bare except Exception
• USAGE/TOOL_REFERENCE mit echten Output-Beispielen
• check-mcp.sh mit echtem Smoke-Test (kein 'command -v' nur)

.gitignore: .hermes/, .pytest_cache/, .ruff_cache/ hinzugefügt.

Summary

Type of change

• feat — new skill / MCP server / workflow
• fix — bug fix
• docs — documentation only
• chore — maintenance (deps, config, scripts)
• refactor — code change without new features

Checklist

• No secrets or tokens committed (.env is in .gitignore)
• If adding a skill: SKILL.md has name, description, triggers frontmatter
• If adding a skill: python3 scripts/build_index.py has been run locally
• If adding an MCP server: entry added to .mcp.json with ${ENV_VAR} references only
• If adding an MCP server: env var added to .env.example
• CI passes (secret-scanning, skill-lint, mcp-health-check)

Related

[Toqsick]

@copilot resolve the merge conflicts in this pull request

[Copilot]

Pull request overview

Introduces a local Python/FastMCP stdio MCP server (mcp-server-basti) with three tools (system status via uptime, an echo_tool health-check, and repository info via git), plus CI, tests, docs, and plugin configuration to run it via uv.

Changes:

• Add mcp_server_basti stdio server implementation with structured stderr JSON logging and ToolResult-based error signaling.
• Add unit + stdio integration tests validating tool discovery, success paths, and structured error behavior.
• Add packaging (pyproject.toml), CI workflow, docs/README updates, and .mcp.json entry for basti-tools.

Reviewed changes

Copilot reviewed 18 out of 23 changed files in this pull request and generated 6 comments.

Show a summary per file

File	Description
tests/unit/test_system_status.py	Unit tests for get_system_status output shape/content.
tests/unit/test_repo_info.py	Unit tests verifying get_repo_info includes branch/commit info.
tests/unit/test_echo_tool.py	Unit tests for echo_tool passthrough behavior.
tests/unit/init.py	Marks unit test package.
tests/integration/test_tool_discovery.py	Integration tests ensuring exactly three tools are advertised.
tests/integration/test_error_handling.py	Integration tests for structured errors and session survivability.
tests/integration/test_echo_integration.py	Integration tests calling echo_tool over stdio transport.
tests/integration/conftest.py	Shared stdio server params + timeout fixture.
tests/integration/init.py	Marks integration test package.
tests/init.py	Marks tests package.
src/mcp_server_basti/server.py	Implements FastMCP server + the 3 tools + structured error helpers.
src/mcp_server_basti/logging_setup.py	Adds structured JSON logging to stderr to avoid stdio stream corruption.
src/mcp_server_basti/init.py	Package init + version.
server.json	Server metadata/manifest describing tools and runtime/transport.
scripts/check-mcp.sh	Health-check script for .mcp.json servers (PATH/env + smoke-test for basti-tools).
README.md	Adds documentation section for the new MCP server, config, and usage.
pyproject.toml	Packaging + entry point (mcp-server-basti) + pytest config.
plugins/agent-toolkit/.mcp.json	Registers basti-tools server using uv and ${CLAUDE_PROJECT_ROOT}.
docs/mcp-server/USAGE.md	Usage and troubleshooting guide for running/configuring the server.
docs/mcp-server/TOOL_REFERENCE.md	Tool reference and examples, including error format.
.gitignore	Ignores pytest/ruff caches and local Hermes data.
.github/workflows/ci.yml	Adds CI for lint (ruff), tests (pytest via uv), and build + wheel smoke-test.

Suppressed comments (2)

README.md:295

• Im .mcp.json-Beispiel ist der --directory-Pfad hardcodiert. Das widerspricht der im Repo verwendeten Konfiguration in plugins/agent-toolkit/.mcp.json (nutzt ${CLAUDE_PROJECT_ROOT}) und macht die Doku host-spezifisch.

      "args": [
        "run",
        "--directory", "/home/bratan/ZCodeProject/my-agent-tools",
        "mcp-server-basti"

README.md:310

• Auch im Test-Abschnitt ist der Pfad hardcodiert. Bitte auf einen Platzhalter umstellen, damit die Anleitung plattform-/userunabhängig ist.

cd /home/bratan/ZCodeProject/my-agent-tools
uv sync --all-extras
uv run pytest tests/unit tests/integration -v

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

@copilot resolve the merge conflicts in this pull request

Merged origin/main and resolved conflicts in .gitignore, plugins/agent-toolkit/.mcp.json, and scripts/check-mcp.sh (kept Basti's JSON-output health-check script since it's what the shellcheck job and smoke test expect). Tests still pass (18/18) in c029f95.

[Toqsick]

@copilot Fix the code for all comments in this review thread.

When a review comment includes a suggested change, apply the suggestion exactly.

Do not make changes beyond what is described in the linked review thread.

[Toqsick]

Review okay