@ngocsangairvds/vsaf 3.1.27 → 3.2.2

package/tools/vds-scripts/mcp_server/Dockerfile

@@ -0,0 +1,34 @@
+# syntax=docker/dockerfile:1
+FROM python:3.12-slim
+
+# Install system dependencies
+RUN apt-get update && apt-get install -y \
+    curl \
+    ca-certificates \
+    git \
+    && rm -rf /var/lib/apt/lists/*
+
+# Install uv
+RUN curl -LsSf https://astral.sh/uv/install.sh | sh
+
+# Set PATH for uv
+ENV PATH="/root/.local/bin:/root/.cargo/bin:$PATH"
+ENV UV_SYSTEM_PYTHON=1
+
+# Set working directory
+WORKDIR /app
+
+# Copy MCP server
+COPY mcp_server /app/mcp_server
+
+# Install MCP server
+RUN cd /app/mcp_server && \
+    uv sync --frozen --project /app/mcp_server
+
+# Health check
+HEALTHCHECK --interval=30s --timeout=10s --start-period=5s --retries=3 \
+    CMD uv run --project /app/mcp_server vds-mcp-server --help || exit 1
+
+# Default command
+ENTRYPOINT ["uv", "run", "--project", "/app/mcp_server", "vds-mcp-server"]
+

package/tools/vds-scripts/mcp_server/README.md

@@ -0,0 +1,140 @@
+# VDS MCP Server
+
+Model Context Protocol (MCP) server for VDS Platform operations, enabling AI agents to interact with JIRA, Confluence,
+Bitbucket, and Git through a standardized interface.
+
+## Installation
+
+```bash
+cd vds-scripts
+# Optional: sync every package once
+./scripts/bootstrap_uv.sh
+
+# Package-specific sync (only when you need dev extras)
+uv sync --project mcp_server
+```
+
+## Usage
+
+### Start MCP Server
+
+```bash
+# Using stdio transport (default)
+uv run vds-mcp-server
+
+# Or directly
+uv run --project mcp_server python -m vds_mcp_server.server
+```
+
+### Available Tools
+
+The MCP server exposes the following tools:
+
+#### JIRA Tools
+
+- `jira_search` - Search JIRA issues using JQL query
+- `jira_get_issue` - Get JIRA issue details
+- `jira_list_projects` - List all JIRA projects
+
+#### Confluence Tools
+
+- `confluence_search` - Search Confluence content using CQL query
+- `confluence_get_page` - Get Confluence page content
+
+#### Bitbucket Tools
+
+- `bitbucket_list_projects` - List all Bitbucket projects
+- `bitbucket_list_repositories` - List repositories in a project
+
+#### Git Tools
+
+- `git_clone` - Clone a VDS project repository
+- `git_status` - Get Git repository status
+- `git_pull` - Pull latest changes from Git repositories
+
+## Client Integration
+
+### Claude Desktop Configuration
+
+Add to `~/Library/Application Support/Claude/claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "vds-orchestrator": {
+      "command": "uv",
+      "args": [
+        "run",
+        "--project",
+        "/path/to/vds-scripts/mcp_server",
+        "vds-mcp-server"
+      ],
+      "env": {
+        "VDS_USERNAME": "${VDS_USERNAME}",
+        "VDS_PASSWORD": "${VDS_PASSWORD}",
+        "BITBUCKET_ACCESS_TOKEN": "${BITBUCKET_ACCESS_TOKEN}",
+        "INTERNAL_CONFLUENCE_TOKEN": "${INTERNAL_CONFLUENCE_TOKEN}",
+        "EXTERNAL_CONFLUENCE_TOKEN": "${EXTERNAL_CONFLUENCE_TOKEN}"
+      }
+    }
+  }
+}
+```
+
+### Using with Docker
+
+```bash
+cd vds-scripts/docker
+docker-compose up -d mcp-server
+```
+
+## Development
+
+### Running Tests
+
+```bash
+# Unit tests
+uv run --project mcp_server pytest tests/unit/ -v
+
+# Verification tests (requires credentials)
+uv run --project mcp_server pytest tests/verification/ -v
+
+# With coverage
+uv run --project mcp_server pytest tests/ -v --cov=vds_mcp_server --cov-report=term-missing
+```
+
+### Code Quality
+
+```bash
+# Lint check
+uv run --project mcp_server ruff check src/
+
+# Format code
+uv run --project mcp_server ruff format src/
+```
+
+## Architecture
+
+The MCP server uses:
+
+- **FastMCP**: High-level MCP server interface from official Python SDK
+- **VDS CLI**: Executes commands via `vds-cli` subprocess
+- **Tool Registration**: All tools registered at server startup
+
+## Requirements
+
+- Python >= 3.11
+- uv (for package management)
+- vds-cli (must be installed and available in PATH)
+- Environment file at `~/.vds/.env` with credentials
+
+## Dependencies
+
+- **mcp** >= 1.0.0 - Official MCP Python SDK (Context7: `/modelcontextprotocol/python-sdk`)
+- **typer** >= 0.20.0 - CLI framework
+- **pydantic** >= 2.12.3 - Data validation
+- **pydantic-settings** >= 2.12.0 - Settings management
+
+______________________________________________________________________
+
+*Last updated: 2025-11-12*

package/tools/vds-scripts/mcp_server/pyproject.toml

@@ -0,0 +1,42 @@
+[project]
+name = "vds-mcp-server"
+version = "1.0.0"
+description = "Model Context Protocol server for VDS Platform operations"
+requires-python = ">=3.11"
+dependencies = [
+    "mcp>=1.0.0",                    # Official MCP Python SDK - Context7: /modelcontextprotocol/python-sdk
+    "typer>=0.20.0",                # CLI framework
+    "pydantic>=2.12.3",             # Data validation
+    "pydantic-settings>=2.12.0",    # Settings management
+]
+
+[project.scripts]
+vds-mcp-server = "vds_mcp_server.server:main"
+
+[build-system]
+requires = ["hatchling>=1.20.0"]
+build-backend = "hatchling.build"
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=9.0.1",
+    "pytest-cov>=5.0.0",
+    "pytest-asyncio>=0.24.0",
+    "ruff>=0.14.5",
+]
+
+[tool.uv]
+package = true
+
+[tool.uv.sources]
+vds_mcp_server = { path = "src" }
+
+
+[dependency-groups]
+dev = [
+    "pytest>=9.0.1",
+    "pytest-cov>=5.0.0",
+    "pytest-asyncio>=0.24.0",
+    "ruff>=0.14.5",
+]
+

package/tools/vds-scripts/mcp_server/src/vds_mcp_server/__init__.py

@@ -0,0 +1,4 @@
+"""VDS MCP Server - Model Context Protocol server for VDS Platform operations."""
+
+__version__ = "1.0.0"
+

package/tools/vds-scripts/mcp_server/src/vds_mcp_server/config.py

@@ -0,0 +1,36 @@
+"""Configuration management for MCP server.
+
+Based on pydantic-settings v2.12.0+ API
+Context7: /pydantic/pydantic-settings
+"""
+
+from pathlib import Path
+
+from pydantic_settings import BaseSettings, SettingsConfigDict
+
+
+class MCPServerSettings(BaseSettings):
+    """MCP server configuration settings."""
+
+    model_config = SettingsConfigDict(
+        env_file=Path.home() / ".vds" / ".env",
+        env_file_encoding="utf-8",
+        case_sensitive=False,
+    )
+
+    # VDS credentials (required for orchestrator operations)
+    vds_username: str | None = None
+    vds_password: str | None = None
+    bitbucket_access_token: str | None = None
+    internal_confluence_token: str | None = None
+    external_confluence_token: str | None = None
+
+    # MCP server settings
+    server_name: str = "vds-orchestrator"
+    server_version: str = "1.0.0"
+
+
+def load_settings() -> MCPServerSettings:
+    """Load MCP server settings from environment."""
+    return MCPServerSettings()
+

package/tools/vds-scripts/mcp_server/src/vds_mcp_server/server.py

@@ -0,0 +1,66 @@
+"""MCP Server for VDS Platform operations.
+
+Based on MCP Python SDK v1.0.0+
+Context7: /modelcontextprotocol/python-sdk
+Key Features: FastMCP, tool registration, stdio transport
+"""
+
+import subprocess
+from typing import Any
+
+from mcp.server.fastmcp import FastMCP
+
+from .config import load_settings
+from .tools import (
+    register_bitbucket_tools,
+    register_confluence_tools,
+    register_git_tools,
+    register_jira_tools,
+)
+
+# Initialize FastMCP server
+mcp = FastMCP("VDS Orchestrator")
+
+
+async def execute_vds_cli(*args: str) -> dict[str, Any]:
+    """Execute VDS CLI command via subprocess.
+
+    Args:
+        *args: Command arguments to pass to vds-cli
+
+    Returns:
+        dict: Command execution result with stdout, stderr, returncode
+    """
+    cmd = ["vds-cli"] + list(args)
+    result = subprocess.run(
+        cmd,
+        capture_output=True,
+        text=True,
+        check=False,
+    )
+    return {
+        "stdout": result.stdout,
+        "stderr": result.stderr,
+        "returncode": result.returncode,
+    }
+
+
+# Register all tool modules
+register_jira_tools(mcp, execute_vds_cli)
+register_confluence_tools(mcp, execute_vds_cli)
+register_bitbucket_tools(mcp, execute_vds_cli)
+register_git_tools(mcp, execute_vds_cli)
+
+
+def main() -> None:
+    """Main entry point for MCP server."""
+    # Load settings to ensure environment is configured
+    load_settings()
+
+    # Run server with stdio transport (default)
+    mcp.run()
+
+
+if __name__ == "__main__":
+    main()
+

package/tools/vds-scripts/mcp_server/src/vds_mcp_server/tools/__init__.py

@@ -0,0 +1,14 @@
+"""MCP tools for VDS Platform orchestrators."""
+
+from .bitbucket_tools import register_bitbucket_tools
+from .confluence_tools import register_confluence_tools
+from .git_tools import register_git_tools
+from .jira_tools import register_jira_tools
+
+__all__ = [
+    "register_jira_tools",
+    "register_confluence_tools",
+    "register_bitbucket_tools",
+    "register_git_tools",
+]
+

package/tools/vds-scripts/mcp_server/src/vds_mcp_server/tools/bitbucket_tools.py

@@ -0,0 +1,47 @@
+"""Bitbucket tools for MCP server.
+
+Based on MCP Python SDK v1.0.0+
+Context7: /modelcontextprotocol/python-sdk
+"""
+
+from collections.abc import Callable
+from typing import Any
+
+from mcp.server.fastmcp import FastMCP
+
+
+def register_bitbucket_tools(mcp: FastMCP, execute_cli: Callable[..., Any]) -> None:
+    """Register Bitbucket tools with MCP server.
+
+    Args:
+        mcp: FastMCP server instance
+        execute_cli: Function to execute VDS CLI commands
+    """
+
+    @mcp.tool()
+    async def bitbucket_list_projects() -> str:
+        """List all Bitbucket projects.
+
+        Returns:
+            str: JSON-formatted list of projects
+        """
+        result = await execute_cli("bitbucket", "projects")
+        if result["returncode"] != 0:
+            return f"Error: {result['stderr']}"
+        return result["stdout"]
+
+    @mcp.tool()
+    async def bitbucket_list_repositories(project_key: str) -> str:
+        """List repositories in a Bitbucket project.
+
+        Args:
+            project_key: Project key (e.g., "LEP")
+
+        Returns:
+            str: JSON-formatted list of repositories
+        """
+        result = await execute_cli("bitbucket", "repositories", project_key)
+        if result["returncode"] != 0:
+            return f"Error: {result['stderr']}"
+        return result["stdout"]
+

package/tools/vds-scripts/mcp_server/src/vds_mcp_server/tools/confluence_tools.py

@@ -0,0 +1,59 @@
+"""Confluence tools for MCP server.
+
+Based on MCP Python SDK v1.0.0+
+Context7: /modelcontextprotocol/python-sdk
+"""
+
+from collections.abc import Callable
+from typing import Any
+
+from mcp.server.fastmcp import FastMCP
+
+
+def register_confluence_tools(mcp: FastMCP, execute_cli: Callable[..., Any]) -> None:
+    """Register Confluence tools with MCP server.
+
+    Args:
+        mcp: FastMCP server instance
+        execute_cli: Function to execute VDS CLI commands
+    """
+
+    @mcp.tool()
+    async def confluence_search(
+        query: str, server: str = "internal", limit: int = 10
+    ) -> str:
+        """Search Confluence content using CQL query.
+
+        Args:
+            query: CQL query string (e.g., "space = TDOV")
+            server: Server to query ("internal" or "external", default: "internal")
+            limit: Maximum number of results (default: 10)
+
+        Returns:
+            str: JSON-formatted search results
+        """
+        result = await execute_cli(
+            "confluence", "content", "search", query, f"--server={server}", f"--limit={limit}"
+        )
+        if result["returncode"] != 0:
+            return f"Error: {result['stderr']}"
+        return result["stdout"]
+
+    @mcp.tool()
+    async def confluence_get_page(page_id: str, server: str = "internal") -> str:
+        """Get Confluence page content.
+
+        Args:
+            page_id: Page ID (e.g., "99647801")
+            server: Server to query ("internal" or "external", default: "internal")
+
+        Returns:
+            str: JSON-formatted page content
+        """
+        result = await execute_cli(
+            "confluence", "content", "page", page_id, f"--server={server}"
+        )
+        if result["returncode"] != 0:
+            return f"Error: {result['stderr']}"
+        return result["stdout"]
+

package/tools/vds-scripts/mcp_server/src/vds_mcp_server/tools/git_tools.py

@@ -0,0 +1,71 @@
+"""Git tools for MCP server.
+
+Based on MCP Python SDK v1.0.0+
+Context7: /modelcontextprotocol/python-sdk
+"""
+
+from collections.abc import Callable
+from typing import Any
+
+from mcp.server.fastmcp import FastMCP
+
+
+def register_git_tools(mcp: FastMCP, execute_cli: Callable[..., Any]) -> None:
+    """Register Git tools with MCP server.
+
+    Args:
+        mcp: FastMCP server instance
+        execute_cli: Function to execute VDS CLI commands
+    """
+
+    @mcp.tool()
+    async def git_clone(project: str) -> str:
+        """Clone a VDS project repository.
+
+        Args:
+            project: Project name (e.g., "lep", "insurance")
+
+        Returns:
+            str: Clone operation result
+        """
+        result = await execute_cli("git", "clone", project)
+        if result["returncode"] != 0:
+            return f"Error: {result['stderr']}"
+        return result["stdout"]
+
+    @mcp.tool()
+    async def git_status(match: str | None = None) -> str:
+        """Get Git repository status.
+
+        Args:
+            match: Pattern to match repositories (e.g., "*service*")
+
+        Returns:
+            str: Status information for matching repositories
+        """
+        args = ["git", "status"]
+        if match:
+            args.extend(["--match", match])
+        result = await execute_cli(*args)
+        if result["returncode"] != 0:
+            return f"Error: {result['stderr']}"
+        return result["stdout"]
+
+    @mcp.tool()
+    async def git_pull(project: str | None = None) -> str:
+        """Pull latest changes from Git repositories.
+
+        Args:
+            project: Project name to pull (optional, pulls all if not specified)
+
+        Returns:
+            str: Pull operation result
+        """
+        args = ["git", "pull"]
+        if project:
+            args.extend(["--project", project])
+        result = await execute_cli(*args)
+        if result["returncode"] != 0:
+            return f"Error: {result['stderr']}"
+        return result["stdout"]
+

package/tools/vds-scripts/mcp_server/src/vds_mcp_server/tools/jira_tools.py

@@ -0,0 +1,63 @@
+"""JIRA tools for MCP server.
+
+Based on MCP Python SDK v1.0.0+
+Context7: /modelcontextprotocol/python-sdk
+"""
+
+from collections.abc import Callable
+from typing import Any
+
+from mcp.server.fastmcp import FastMCP
+
+
+def register_jira_tools(mcp: FastMCP, execute_cli: Callable[..., Any]) -> None:
+    """Register JIRA tools with MCP server.
+
+    Args:
+        mcp: FastMCP server instance
+        execute_cli: Function to execute VDS CLI commands
+    """
+
+    @mcp.tool()
+    async def jira_search(query: str, limit: int = 20) -> str:
+        """Search JIRA issues using JQL query.
+
+        Args:
+            query: JQL query string (e.g., "project = NTTC")
+            limit: Maximum number of results (default: 20)
+
+        Returns:
+            str: JSON-formatted search results
+        """
+        result = await execute_cli("jira", "search", query, f"--limit={limit}")
+        if result["returncode"] != 0:
+            return f"Error: {result['stderr']}"
+        return result["stdout"]
+
+    @mcp.tool()
+    async def jira_get_issue(issue_key: str) -> str:
+        """Get JIRA issue details.
+
+        Args:
+            issue_key: Issue key (e.g., "NTTC-123")
+
+        Returns:
+            str: JSON-formatted issue details
+        """
+        result = await execute_cli("jira", "issue", issue_key)
+        if result["returncode"] != 0:
+            return f"Error: {result['stderr']}"
+        return result["stdout"]
+
+    @mcp.tool()
+    async def jira_list_projects() -> str:
+        """List all JIRA projects.
+
+        Returns:
+            str: JSON-formatted list of projects
+        """
+        result = await execute_cli("jira", "projects")
+        if result["returncode"] != 0:
+            return f"Error: {result['stderr']}"
+        return result["stdout"]
+

package/tools/vds-scripts/mcp_server/tests/__init__.py

@@ -0,0 +1,2 @@
+"""Test suite for VDS MCP Server."""
+

package/tools/vds-scripts/mcp_server/tests/conftest.py

@@ -0,0 +1,29 @@
+"""Pytest configuration and fixtures for MCP server tests."""
+
+from collections.abc import AsyncGenerator
+from unittest.mock import Mock
+
+import pytest
+from mcp.client.session import ClientSession
+from mcp.shared.memory import create_connected_server_and_client_session
+from vds_mcp_server.server import mcp
+
+
+@pytest.fixture
+def anyio_backend() -> str:
+    """Use asyncio backend for tests."""
+    return "asyncio"
+
+
+@pytest.fixture
+async def client_session() -> AsyncGenerator[ClientSession]:
+    """Create in-memory MCP client session for testing."""
+    async with create_connected_server_and_client_session(mcp, raise_exceptions=True) as session:
+        yield session
+
+
+@pytest.fixture
+def mock_execute_cli() -> Mock:
+    """Mock CLI execution function."""
+    return Mock(return_value={"stdout": "test output", "stderr": "", "returncode": 0})
+

package/tools/vds-scripts/mcp_server/tests/unit/__init__.py

@@ -0,0 +1,2 @@
+"""Unit tests for VDS MCP Server."""
+

package/tools/vds-scripts/mcp_server/tests/unit/test_bitbucket_tools.py

@@ -0,0 +1,25 @@
+"""Unit tests for Bitbucket tools.
+
+Based on pytest v8.3.3+ API
+Context7: /pytest-dev/pytest
+"""
+
+import pytest
+from mcp.client.session import ClientSession
+
+pytestmark = pytest.mark.anyio
+
+
+async def test_bitbucket_list_projects_tool(client_session: ClientSession) -> None:
+    """Test bitbucket_list_projects tool is available."""
+    tools = await client_session.list_tools()
+    tool_names = [tool.name for tool in tools.tools]
+    assert "bitbucket_list_projects" in tool_names
+
+
+async def test_bitbucket_list_repositories_tool(client_session: ClientSession) -> None:
+    """Test bitbucket_list_repositories tool is available."""
+    tools = await client_session.list_tools()
+    tool_names = [tool.name for tool in tools.tools]
+    assert "bitbucket_list_repositories" in tool_names
+

package/tools/vds-scripts/mcp_server/tests/unit/test_confluence_tools.py

@@ -0,0 +1,25 @@
+"""Unit tests for Confluence tools.
+
+Based on pytest v8.3.3+ API
+Context7: /pytest-dev/pytest
+"""
+
+import pytest
+from mcp.client.session import ClientSession
+
+pytestmark = pytest.mark.anyio
+
+
+async def test_confluence_search_tool(client_session: ClientSession) -> None:
+    """Test confluence_search tool is available."""
+    tools = await client_session.list_tools()
+    tool_names = [tool.name for tool in tools.tools]
+    assert "confluence_search" in tool_names
+
+
+async def test_confluence_get_page_tool(client_session: ClientSession) -> None:
+    """Test confluence_get_page tool is available."""
+    tools = await client_session.list_tools()
+    tool_names = [tool.name for tool in tools.tools]
+    assert "confluence_get_page" in tool_names
+