O'Process

AI-native process classification MCP Server. Query 2,436 processes and 3,284 KPIs from APQC PCF 8.0 + ITIL V5 + SCOR DS 14.0 + AI-era extensions.

Version: 0.5.0 | MCP SDK: Anthropic official mcp 1.26.0 | Protocol: 2025-11-25 | Coverage: 88%+

What It Does

O'Process gives AI assistants (Claude, GPT, etc.) real-time access to enterprise process knowledge. Connect it as an MCP Server, then ask natural language questions — the AI will call the right tools automatically.

Core capabilities:

Process Search — "采购流程有哪些?" → returns matching process nodes with hierarchy, description, and confidence score
Process Tree Navigation — browse the 5-level taxonomy (L1 categories → L5 activities)
KPI Recommendations — get metrics for any process node (name, unit, formula, direction)
Role-Process Mapping — "HRBP manages which processes?" → curated mappings with confidence scores and relation types (primary/shared/supporting)
Role Knowledge Base — 54 curated IT roles across 4 layers (strategy/architecture/delivery/operations) with explicit process mappings
Team Planning — recommend IT roles by team size (small/medium/large)
Process Comparison — side-by-side diff of 2+ process nodes across all attributes
Responsibility Document — generate complete job descriptions with provenance appendix

Why It Matters

| Without O'Process | With O'Process | |-------------------|----------------| | Manually search APQC PCF Excel (2017 rows) | Natural language query, instant results | | Guess which KPIs apply to a process | Structured KPI suggestions from 3,284 metrics | | Write job descriptions from scratch | Auto-generated with process-backed provenance | | Cross-reference APQC + ITIL + SCOR manually | Unified 2,436-node taxonomy, one query |

Use Cases

Management Consulting — Process diagnostics. A manufacturing company's delivery cycle is 30% slower than competitors. Use search_process to locate SCOR Plan/Deliver/Make nodes, then get_kpi_suggestions to build a measurement framework.

HR Digital Transformation — Role-process mapping. CHRO needs to know what processes HR actually owns. Use get_process_tree on node 7.0 (Human Capital) to get the full L1→L4 hierarchy, then map_role_to_processes to map "HRBP" to standard processes.

Legal Due Diligence — Compliance audit. Cross-border M&A requires checking 12+ regulatory domains. Use search_process to locate relevant PCF nodes (corporate governance, tax, labor, environmental), then compare_processes to identify coverage gaps.

Internal Audit — KPI system design. Use get_kpi_suggestions for each process node, review coverage across efficiency/quality/cost/timeliness dimensions, identify missing metrics.

Quick Start

# Install
uv sync

# Run MCP Server (stdio — default)
uv run python -m oprocess.server

# Run with SSE transport
uv run python -m oprocess.server --transport sse --port 8000

# Run with streamable-http transport
uv run python -m oprocess.server --transport streamable-http --port 8000

Claude Desktop Configuration

Add to claude_desktop_config.json:

{
  "mcpServers": {
    "oprocess": {
      "command": "uv",
      "args": ["run", "python", "-m", "oprocess.server"],
      "cwd": "/path/to/O-Process"
    }
  }
}

Tools

11 MCP tools with full input validation, structured output, and ToolAnnotations:

| Tool | Description | Key Parameters | |------|-------------|----------------| | search_process | Semantic search for process nodes | query (1-500 chars), lang (zh/en), limit (1-50), level (1-5) | | get_process_tree | Get process subtree with children | process_id (e.g. "1.0"), max_depth (1-5) | | get_kpi_suggestions | Get KPIs for a process node | process_id | | compare_processes | Compare 2+ process nodes side-by-side | process_ids (comma-separated, 2+) | | get_responsibilities | Generate role responsibilities | process_id, lang, output_format (json/markdown) | | map_role_to_processes | Map job role to processes (curated-first, semantic fallback) | role_description (1-500 chars), lang, limit, industry | | export_responsibility_doc | Export full responsibility document | process_ids (1+), lang, role_name | | list_roles | List all 54 curated IT roles | lang, layer (strategy/architecture/delivery/operations) | | get_role_definition | Get role profile with mapped processes | role_id (e.g. "sre"), lang | | plan_it_roles | Recommend IT roles by team size | team_size (small/medium/large), lang | | health_check | Health check — server status and data counts | _(none)_ |

All tools return structured content (structuredContent + text) with result, provenance_chain, session_id, and response_ms. Each tool has outputSchema auto-generated from Pydantic models.

Invalid inputs raise ToolError (Tool Execution Error for LLM self-correction). All tools are annotated with readOnlyHint, idempotentHint, destructiveHint, and openWorldHint.

Role Knowledge Base (v0.5.0)

54 curated IT roles organized in 4 layers:

| Layer | Roles | Examples | |-------|-------|---------| | Strategy & Governance | 10 | CIO/CTO, CISO, Enterprise Architect, IT Auditor | | Requirements & Architecture | 8 | Business Analyst, Solution Architect, Data Architect, UX/UI Designer | | Delivery & Engineering | 15 | Developer, QA Engineer, DevOps, Release Manager, Scrum Master | | Operations & Service | 21 | SRE, Capacity Planner, Service Desk, Change Manager, SOC Manager |

Each role includes bilingual (zh/en) definitions, aliases for fuzzy matching, explicit process mappings with confidence scores, and min_team_size thresholds for team planning.

Prompts

3 guided prompt templates for common workflows:

| Prompt | Description | Parameters | |--------|-------------|------------| | analyze_process | Step-by-step process analysis workflow | process_id, lang | | generate_job_description | Role responsibility document generation | process_ids, role_name, lang | | kpi_review | KPI review and gap analysis workflow | process_id, lang |

Resources

6 MCP resources for direct data access:

| URI | Title | Description | |-----|-------|-------------| | oprocess://process/{id} | Process Node | Complete process node data | | oprocess://category/list | Category List | All L1 process categories | | oprocess://role/{role_name} | Role-Process Mapping | Process mappings for a role | | oprocess://audit/session/{id} | Audit Session Log | Audit log for a session | | oprocess://schema/sqlite | SQLite Schema | Public table schema (processes, kpis) | | oprocess://stats | Framework Statistics | Process/KPI counts and version |

Authentication

For HTTP transports (SSE, streamable-http), authentication is handled at the reverse-proxy layer (e.g. Caddy with forward_auth or bearer_token directive). See deploy/README.md for Caddy configuration.

stdio mode requires no authentication (local process communication).

Environment Variables

| Variable | Required | Description | |----------|----------|-------------| | GOOGLE_API_KEY | No | Enables semantic vector search (gemini-embedding-001). Without it, search falls back to SQL LIKE matching — all features still work. | | OPROCESS_API_KEY | No | Bearer token for reverse-proxy auth layer. | | OPROCESS_ALLOWED_ORIGINS | No | Comma-separated allowed origins for CORS. | | LOG_LEVEL | No | Logging level (default: INFO) |

No API key is required to run the server. All 11 tools work out of the box. Setting GOOGLE_API_KEY upgrades search_process and map_role_to_processes from text matching to semantic vector search.

Logging

Structured JSON logging (no extra dependencies):

# Default level: INFO (all tool calls logged)
export LOG_LEVEL=DEBUG  # DEBUG, INFO, WARNING, ERROR

# Output format (JSON):
# {"ts":"2026-03-16 12:00:00","level":"INFO","logger":"oprocess","msg":"tool.execute","tool":"search_process","session_id":"...","ms":4}

Configuration

Server behavior can be tuned via [tool.oprocess] in pyproject.toml:

| Key | Default | Description | |-----|---------|-------------| | boundary_threshold | 0.45 | Cosine distance threshold for BoundaryResponse | | audit_log_enabled | true | Enable/disable SessionAuditLog | | default_language | "zh" | Default language (zh/en) | | rate_limit_max_calls | 60 | Max tool calls per window | | rate_limit_window_seconds | 60 | Rate limit window duration (seconds) |

Rate limiting is enforced via thread-safe RateLimiter. Exceeding the limit returns MCP error code -32000.

Governance-Lite

Transparent governance layer (non-blocking):

SessionAuditLog — Append-only invocation log per session (failure-tolerant with escalation)
BoundaryResponse — Structured fallback when semantic confidence is low (threshold: 0.45)
ProvenanceChain — Derivation trail attached to every tool response
Prompt Injection Mitigation — Description fields sanitized with [DATA_BEGIN]/[DATA_END] markers

Data Sources

| Source | Entries | License | |--------|---------|---------| | APQC PCF 8.0 | 2,017 processes | Royalty-free with attribution | | ITIL V5 | 145 nodes | Practice names only (industry terms) | | SCOR DS 14.0 | 175 nodes | Open-access standard | | AI-era extensions | 99 nodes | Original (MIT) | | Total | 2,436 processes | | | KPI metrics | 3,284 | From APQC PCF 8.0 Metrics | | IT Role definitions | 54 roles, 253 mappings | Curated (MIT) |

Bilingual: Chinese (zh) + English (en).

Third-Party Attribution

APQC Process Classification Framework® (PCF) is an open standard developed by APQC, a nonprofit that promotes benchmarking and best practices worldwide. Used under APQC's royalty-free license for derivative works. To download the original PCF, visit apqc.org/pcf.

ITIL® is a registered trademark of PeopleCert group. This project references ITIL V5 practice names as industry-standard terminology. All descriptions are independently written and are not reproduced from ITIL publications.

SCOR® (Supply Chain Operations Reference) is a product of ASCM. This project references SCOR DS 14.0 process names as open-access industry-standard terminology. All descriptions are independently written.

Development

# Install dependencies
uv sync

# Lint
ruff check .

# Test (284 tests, 88%+ coverage)
pytest

# Full check (lint + test + benchmark)
ruff check . && pytest && pytest --benchmark-only

Project Structure

src/oprocess/
├── server.py              # MCP entry point (stdio/SSE/HTTP)
├── gateway.py             # ToolGatewayInterface + PassthroughGateway
├── config.py              # pyproject.toml config loader
├── validators.py          # Input validation + sanitization
├── prompts.py             # 3 MCP prompt templates
├── tools/
│   ├── registry.py        # Tool registration orchestrator
│   ├── search.py          # search_process + map_role_to_processes
│   ├── roles.py           # list_roles + get_role_definition + plan_it_roles
│   ├── resources.py       # 6 MCP resources
│   ├── _models.py         # Pydantic response models
│   ├── export.py          # Responsibility document builder
│   ├── helpers.py         # Provenance + comparison utilities
│   ├── serialization.py   # ToolResponse → ToolEnvelope
│   └── rate_limit.py      # Thread-safe rate limiter
├── governance/
│   ├── audit.py           # SessionAuditLog
│   ├── boundary.py        # BoundaryResponse
│   └── provenance.py      # ProvenanceChain
└── db/
    ├── connection.py       # SQLite + sqlite-vec connection
    ├── queries.py          # Process + KPI SQL queries
    ├── role_queries.py     # Role knowledge base queries
    ├── embedder.py         # Gemini embedding (with timeout + retry)
    └── vector_search.py    # sqlite-vec vector search

Tech Stack

Runtime: Python 3.10+
MCP SDK: Anthropic official mcp 1.26.0 (mcp.server.fastmcp)
Protocol: MCP 2025-11-25 (structured output, ToolAnnotations, title)
Validation: Pydantic 2.x (Annotated[..., Field(...)])
Database: SQLite + sqlite-vec (optional vector search)
Embeddings: gemini-embedding-001 (768-dim, 5s timeout, 2-retry)
Packaging: uv + hatchling

Deployment

See deploy/README.md for production deployment on Alibaba Cloud with Caddy reverse proxy.

Live endpoint: http://8.138.46.17/mcp (streamable-http)

License

MIT — applies to all source code and AI-era original content.

Third-party framework data (APQC PCF, ITIL, SCOR) is used under their respective licenses. See Third-Party Attribution for details.

O-Process