Skip to content

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

Open
123yongming wants to merge 3 commits intovolcengine:mainfrom
123yongming:feature/mcp
Open

feat(mcp): add MCP stdio server with access-level gated tools)#305
123yongming wants to merge 3 commits intovolcengine:mainfrom
123yongming:feature/mcp

Conversation

@123yongming
Copy link

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).

- Update _optional_int to exclude bool type (isinstance bool is int subclass)
- Add parametrized tests for limit/offset with true/false values
- Add MCP server module and CLI mcp command
- Update README with MCP server documentation
- Add four-tier access level model: readonly < ingest < mutate < admin
- Expose session, relation, filesystem, and pack tools gated by level
- Register backward-compatible alias openviking_add_resource -> openviking_resource_add
- CLI: --enable-write maps to --access-level mutate for compatibility
- Tests: all 45 MCP tests pass (3 skipped, 0 failed)
@CLAassistant
Copy link

CLA assistant check
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
Copy link
Collaborator

ZaynJarvis commented Feb 26, 2026

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.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

Status: Backlog

Development

Successfully merging this pull request may close these issues.

3 participants