feat(mcp): add MCP stdio server with access-level gated tools）

[123yongming]

Description

This PR introduces OpenViking MCP Server V1 support in embedded mode (stdio transport), including:

• a new MCP runtime module with tool dispatching and access-level gating (readonly / ingest / mutate / admin)
• a new CLI entrypoint openviking mcp with --access-level and compatibility flag --enable-write
• MCP optional dependency wiring and user-facing documentation updates (EN/CN)

It also improves argument validation in MCP tool dispatch (e.g. rejecting boolean values for integer fields).

Related Issue

N/A

Type of Change

• Bug fix (non-breaking change that fixes an issue)
• New feature (non-breaking change that adds functionality)
• Breaking change (fix or feature that would cause existing functionality to not work as expected)
• Documentation update
• Refactoring (no functional changes)
• Performance improvement
• Test update

Changes Made

• Added new MCP package and runtime implementation:
  • openviking/mcp/__init__.py
  • openviking/mcp/permissions.py
  • openviking/mcp/server.py
  • openviking/mcp/tools.py
• Added CLI command integration for MCP server:
  • openviking_cli/cli/commands/mcp.py
  • command registration update in openviking_cli/cli/commands/__init__.py
• Added MCP optional dependency in pyproject.toml ([project.optional-dependencies].mcp)
• Added/updated tests:
  • tests/mcp/test_tools.py
  • tests/mcp/test_server.py
  • tests/mcp/test_protocol_stdio.py
  • tests/cli/test_cli.py
  • tests/cli/conftest.py
• Updated documentation:
  • README.md
  • README_CN.md

Testing

• I have added tests that prove my fix is effective or that my feature works
• New and existing unit tests pass locally with my changes
• I have tested this on the following platforms:
  • Linux
  • macOS
  • Windows

Notes:

• Syntax validation completed for key modified modules via python -m py_compile.
• Full local pytest execution was not completed in this environment (missing pytest dependency); CI is expected to validate lint/test suite.

Checklist

• My code follows the project's coding style
• I have performed a self-review of my code
• I have commented my code, particularly in hard-to-understand areas
• I have made corresponding changes to the documentation
• My changes generate no new warnings
• Any dependent changes have been merged and published

Screenshots (if applicable)

N/A

Additional Notes

• This PR is designed to be non-breaking. Existing behavior remains unchanged outside MCP additions.
• A compatibility path is included for write-enable semantics via CLI flag mapping.
• If required by maintainers, I can split this PR into smaller follow-ups (core MCP runtime / CLI / docs).

[CLAassistant]

Thank you for your submission! We really appreciate it. Like many open source projects, we ask that you sign our Contributor License Agreement before we can accept your contribution.
_{You have signed the CLA already but the status is still pending? Let us recheck it.}

[ZaynJarvis]

thx. I will look into this feature.
I will mainly focus on whether l stdio mode, when installed in multiple apps, would result in agfs port conflict?

If that’s true mcp http mode is better to share agfs resource. But http mode mcp server is implemented on top of ov server.

[ZaynJarvis]

Review: Existing HTTP Server vs New MCP Implementation

Hi @123yongming, great work on this MCP server implementation! I did some research on the current codebase and wanted to share insights that might help the review:

Current State of OpenViking Server

OpenViking already has a comprehensive HTTP Server implementation using FastAPI:

Component	Location	Purpose
Main app	openviking/server/app.py	FastAPI application setup
Routers	openviking/server/routers/*.py	HTTP endpoints for filesystem, search, sessions, resources, relations, admin, system
Service layer	openviking/service/core.py	OpenVikingService business logic
Launch	openviking server start	Production HTTP server mode

What This PR Adds

Your PR introduces a new MCP stdio server at openviking/mcp/:

• server.py - MCP FastMCP runtime with stdio transport
• tools.py - Tool definitions and dispatcher
• permissions.py - Access level gating (readonly/ingest/mutate/admin)

Key Insight

These are complementary, not duplicate:

Feature	HTTP Server	MCP Server (this PR)
Transport	HTTP	stdio
Use case	Remote/production	Local MCP host integration
Lifecycle	Long-running daemon	Host-spawned per session
Clients	Multiple concurrent	Single host connection
Example hosts	Custom agents	Claude Desktop, Codex, OpenCode

Suggestion for Future Iteration

Consider leveraging the existing HTTP server as a backend for an MCP-over-SSE or MCP-over-HTTP transport. This would allow:

1. Resource sharing - Multiple MCP hosts connect to one shared OpenViking instance
2. Persistence - Context survives MCP client reconnections
3. Remote MCP - Connect to OpenViking over network

The current stdio implementation is perfect for local embedded use. A future PR could add:

# Hypothetical future extension
openviking mcp --transport sse --url http://localhost:8000

This would bridge your excellent MCP tool layer with the existing HTTP infrastructure.

Great work on the four-tier access model and comprehensive test coverage!