9  Architecture Design Description

9.1 Architecture Viewpoints

Per [1, Sec. 2.3.5.4], architecture viewpoints frame stakeholder concerns.

Viewpoint	Stakeholder Concern	Addressed In
Functional	What functions does the system perform?	Section 9.7
Information	What data flows through the system?	Section 9.8
Physical	What components exist and how deployed?	Section 9.10
Development	How is the system built and maintained?	Section 9.5, Section 9.6

9.2 System Context Diagram

Per [1, Sec. 2.3.5.4], the context diagram defines the system boundary and external interfaces.

                     ┌───────────────────────────────────┐
                     │         External Systems          │
                     └───────────────────────────────────┘
                                      │
       ┌──────────────────────────────┼──────────────────────────────┐
       │                              │                              │
       ▼                              ▼                              ▼
┌─────────────┐              ┌─────────────┐              ┌─────────────┐
│ MCP Client  │              │   GitLab    │              │  SysML v2   │
│ (Claude,    │              │  Instance   │              │ API Server  │
│  VS Code)   │              │ (SaaS/Self) │              │             │
└──────┬──────┘              └─────────────┘              └─────────────┘
       │                              ▲                          ▲
       │ MCP Protocol                 │ REST API                 │ REST API
       │ (stdio/HTTP)                 │ (HTTPS)                  │ (HTTPS)
       ▼                              │                          │
┌─────────────────────────────────────┴──────────────────────────┴────────┐
│                         SysML v2 MCP Server                             │
│  ┌───────────────────────────────────────────────────────────────────┐  │
│  │                        System Boundary                            │  │
│  │                                                                   │  │
│  │  Tools: sysml_parse, sysml_validate, gitlab_read_file, etc.      │  │
│  │  Resources: sysml://examples/*, gitlab://{project}/{path}        │  │
│  │                                                                   │  │
│  └───────────────────────────────────────────────────────────────────┘  │
└─────────────────────────────────────────────────────────────────────────┘

External Interfaces:

Interface	Protocol	Direction	Description
MCP Client	MCP 2024-11-05 (stdio/HTTP)	Bidirectional	AI tool integration
GitLab API	REST (HTTPS)	Outbound	Repository file access
SysML v2 API	REST (HTTPS)	Outbound	Model query and validation

9.3 Architecture Alternatives

Per [1, Sec. 2.3.5.4], candidate architectures were evaluated before selection. Detailed analysis in Section 3.6.

Alternative	Description	Evaluation
Python + FastMCP	Python-based MCP server	Rejected: additional runtime dependency
TypeScript + official SDK	Node.js-based server	Rejected: heavier deployment footprint
Go + go-sdk	Single static binary	Selected: minimal dependencies, fast builds
Rust + custom impl	Rust-based server	Rejected: no official SDK, higher complexity

9.4 Architecture Selection Rationale

The Go-based architecture was selected based on:

Criterion	Weight	Go	Python	TypeScript
Single binary deployment	High	✓	✗	✗
Container size	Medium	~20MB	~200MB	~150MB
GitLab client maturity	High	✓ (go-gitlab)	✓	✓
Official MCP SDK	High	✓ (Google co-maintained)	✓	✓
Team expertise	Medium	✓	✓	✓

Decision: Go provides optimal balance of deployment simplicity, performance, and SDK support.

9.5 Technology Stack

Component	Technology	Rationale
Language	Go 1.23+	Single static binary, fast builds, excellent GitLab client library
MCP SDK	github.com/modelcontextprotocol/go-sdk v1.2.0	Official SDK, Google co-maintained
GitLab Client	github.com/xanzy/go-gitlab	Mature, supports both gitlab.com and self-hosted
Transport	stdio + HTTP	stdio for local dev, HTTP for remote/CI deployment
Container	Buildah/Podman	OCI-compliant, rootless, CI-friendly
Documentation	Quarto	Markdown-native, GitLab Pages compatible, PDF export

9.6 Repository Structure

open-mcp-sysml/                    # GitLab Group
├── plan/                          # Capstone SE Documentation (Quarto Book)
│   ├── _quarto.yml
│   ├── index.qmd
│   ├── chapters/
│   ├── appendices/
│   └── .gitlab-ci.yml
│
└── open-mcp-sysml/               # Software Product
    ├── cmd/
    │   └── sysmlv2-mcp/
    │       └── main.go
    ├── internal/
    │   ├── server/               # MCP server implementation
    │   ├── gitlab/               # GitLab API integration
    │   ├── sysml/                # SysML v2 API client
    │   └── config/               # Configuration handling
    ├── examples/
    │   └── models/               # Example .sysml files
    ├── testdata/
    ├── Containerfile
    ├── .gitlab-ci.yml
    ├── go.mod
    ├── README.md
    ├── CONTRIBUTING.md
    └── LICENSE

9.7 Component Architecture

┌───────────────────────────────────────────────────────┐
│               MCP Client (Claude, etc.)               │
└───────────────────────────────────────────────────────┘
                            │
                            ▼
┌───────────────────────────────────────────────────────┐
│                   Transport Layer                     │
│                   (stdio / HTTP)                      │
└───────────────────────────────────────────────────────┘
                            │
                            ▼
┌───────────────────────────────────────────────────────┐
│                      MCP Server                       │
│  ┌───────────┐   ┌───────────┐   ┌───────────┐       │
│  │   Tools   │   │ Resources │   │  Prompts  │       │
│  └───────────┘   └───────────┘   └───────────┘       │
└───────────────────────────────────────────────────────┘
                            │
        ┌───────────────────┼───────────────────┐
        ▼                   ▼                   ▼
┌─────────────┐      ┌─────────────┐      ┌─────────────┐
│   GitLab    │      │   SysML     │      │  SysML v2   │
│   Client    │      │   Parser    │      │ API Client  │
└─────────────┘      └─────────────┘      └─────────────┘
        │                                       │
        ▼                                       ▼
┌─────────────┐                          ┌─────────────┐
│ GitLab API  │                          │ SysML v2    │
│(gitlab.com) │                          │ API Server  │
└─────────────┘                          └─────────────┘

9.8 Interface Definitions

9.8.1 MCP Protocol Interface

The server implements MCP 2024-11-05:

• initialize - Protocol handshake
• tools/list - Enumerate available tools
• tools/call - Execute a tool
• resources/list - Enumerate resources
• resources/read - Read a resource

9.8.2 GitLab Interface

type GitLabClient interface {
    ReadFile(project, path, ref string) ([]byte, error)
    ListFiles(project, path, ref string) ([]string, error)
    CreateCommit(project, branch, message string, actions []FileAction) error
    CreateMergeRequest(project, source, target, title string) (*MR, error)
}

9.8.3 SysML v2 API Interface

type SysMLAPIClient interface {
    ListProjects() ([]Project, error)
    GetElement(projectID, commitID, elementID string) (*Element, error)
    Query(projectID, commitID string, query Query) ([]Element, error)
    Validate(content string) (*ValidationResult, error)
}

9.9 Requirements Allocation

Per [1, Sec. 2.3.5.4], requirements are allocated to architecture elements.

Requirement	Architecture Element	Package
FR-MCP-001	MCP Server	cmd/sysmlv2-mcp
FR-MCP-002	Tools Handler	internal/server
FR-MCP-003	HTTP Transport	internal/server
FR-GL-001, FR-GL-002	GitLab Client	internal/gitlab
FR-SYS-001, FR-SYS-002	SysML Parser	internal/sysml
FR-SYS-003, FR-SYS-004	SysML API Client	internal/sysml
NFR-DEP-001	Build Configuration	go.mod, Makefile
NFR-DEP-002	Container Image	Containerfile

9.10 Deployment Architecture

Per [1, Sec. 2.3.5.4], deployment architecture defines how the system operates in its environment.

9.10.1 Deployment Modes

Mode	Transport	Use Case	Configuration
Local Development	stdio	Claude Desktop, VS Code	--transport stdio
CI/CD Integration	HTTP	GitLab CI services	--transport http --port 8080
Container	HTTP	Production deployment	Docker/Podman with port mapping

9.10.2 Container Deployment

┌─────────────────────────────────────────────────────────┐
│                      Host System                        │
│  ┌───────────────────────────────────────────────────┐  │
│  │                 Container (OCI)                   │  │
│  │  ┌─────────────────────────────────────────────┐  │  │
│  │  │  sysmlv2-mcp binary                         │  │  │
│  │  │  - Listens on :8080                         │  │  │
│  │  │  - Env: GITLAB_TOKEN, SYSML_API_URL         │  │  │
│  │  └─────────────────────────────────────────────┘  │  │
│  │                        │                          │  │
│  │                     Port 8080                     │  │
│  └────────────────────────┼──────────────────────────┘  │
│                           │                             │
│                     Port Mapping                        │
└───────────────────────────┼─────────────────────────────┘
                            ▼
                    External Clients

9.11 Development Environment Constraints

Constraint: No local container builds on macOS (no podman machine).

Mitigation:

• Local development uses go build and go test directly
• MCP protocol testing via stdio (no containers required)
• Container builds run exclusively in GitLab CI
• HTTP transport testing deferred to CI or Linux machine

This constraint is documented in the V&V Plan with acceptance criteria adjusted accordingly.

[1]

INCOSE, INCOSE systems engineering handbook, 5th ed. Wiley, 2023.