io.github.UncleTIM-GZ/oprocess
AI-native process classification server. 2325 processes + 3910 KPIs from APQC, ITIL, SCOR.
Ask AI about io.github.UncleTIM-GZ/oprocess
Powered by Claude ยท Grounded in docs
I know everything about io.github.UncleTIM-GZ/oprocess. Ask me about installation, configuration, usage, or troubleshooting.
0/500
Reviews
Documentation
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_KEYupgradessearch_processandmap_role_to_processesfrom 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
mcp1.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.
