sxmc/lib.rs
1//! Sumac (`sxmc`) is a native Rust toolkit that brings out what your tools can
2//! do: skills become MCP servers, MCP servers become terminal workflows, and
3//! APIs become CLIs.
4//!
5//! MCP is an open standard for connecting AI assistants to external tools and
6//! data sources. Sumac removes the need to write separate adapters for each
7//! surface by providing one binary that handles all three while reducing
8//! wrapper sprawl, keeping discovery narrower, and making the same capabilities
9//! reusable across agents, shells, and hosted MCP clients:
10//!
11//! - **Skills → MCP server** — serve skill directories as stdio or HTTP MCP endpoints
12//! - **MCP server → CLI** — turn any MCP server into command-line tools
13//! - **API → CLI** — auto-detect OpenAPI or GraphQL specs and execute operations
14//! with JSON or TOON-style structured output
15//! - **CLI → AI surfaces** — inspect a real CLI into a normalized profile, then
16//! generate startup-facing docs and host config scaffolds
17//!
18//! The crate powers the `sxmc` binary, but it also exposes the building blocks
19//! that the CLI uses internally. That makes it useful if you want to embed
20//! skill discovery, MCP serving, API introspection, or security scanning in a
21//! Rust application of your own.
22//!
23//! # What Sumac does
24//!
25//! Sumac treats a skills directory as structured input:
26//!
27//! - each `SKILL.md` body becomes an MCP prompt
28//! - each file in `scripts/` becomes an MCP tool
29//! - each file in `references/` becomes an MCP resource
30//! - hybrid retrieval tools are added for broad client compatibility
31//!
32//! It also includes clients for:
33//!
34//! - local stdio MCP servers
35//! - remote streamable HTTP MCP servers
36//! - OpenAPI documents
37//! - GraphQL endpoints
38//!
39//! # Module Guide
40//!
41//! - [`skills`] discovers and parses skills
42//! - [`server`] turns parsed skills into an MCP server
43//! - [`client`] connects to MCP, OpenAPI, and GraphQL sources
44//! - [`cli_surfaces`] inspects CLIs and generates startup-facing AI artifacts
45//! - [`security`] scans skills and MCP surfaces for common risks
46//! - [`bake`] stores reusable connection definitions
47//! - [`auth`] resolves secrets from environment variables and files
48//!
49//! # Typical CLI Flows
50//!
51//! The crate is primarily exercised through the `sxmc` binary:
52//!
53//! ```text
54//! sxmc serve --paths ./skills
55//! sxmc stdio "sxmc serve --paths ./skills" --list
56//! sxmc http http://127.0.0.1:8000/mcp --list
57//! sxmc api ./openapi.json --list
58//! sxmc scan --paths ./skills
59//! sxmc inspect cli gh --format toon
60//! ```
61//!
62//! # Embedding in Rust
63//!
64//! A minimal server setup looks like:
65//!
66//! ```no_run
67//! use std::path::PathBuf;
68//!
69//! #[tokio::main]
70//! async fn main() -> Result<(), Box<dyn std::error::Error>> {
71//! let paths = vec![PathBuf::from("./skills")];
72//! sxmc::server::serve_stdio(&paths, false).await?;
73//! Ok(())
74//! }
75//! ```
76//!
77//! For remote serving, use [`server::serve_http`].
78//!
79//! # Security
80//!
81//! `sxmc` includes native scanners for:
82//!
83//! - prompt injection patterns
84//! - hidden Unicode characters and homoglyphs
85//! - embedded secrets
86//! - dangerous script patterns
87//! - suspicious MCP tool descriptions and responses
88//!
89//! The CLI exposes these through `sxmc scan`, and the underlying types are in
90//! [`security`].
91//!
92//! # Acknowledgements
93//!
94//! `sxmc` was informed in part by prior work such as
95//! [`skill-to-mcp`](https://github.com/biocontext-ai/skill-to-mcp), which
96//! helped demonstrate the value of exposing skill collections through MCP.
97
98/// Secret resolution helpers used by CLI and client configuration flows.
99pub mod auth;
100/// Saved connection definitions for MCP servers and APIs.
101pub mod bake;
102/// Lightweight filesystem cache utilities.
103pub mod cache;
104/// CLI inspection and CLI->AI surface generation helpers.
105pub mod cli_surfaces;
106/// MCP, OpenAPI, and GraphQL client adapters.
107pub mod client;
108/// Shared error types used across the crate.
109pub mod error;
110/// Process execution helpers for script-backed tools.
111pub mod executor;
112/// Output formatting helpers for CLI rendering.
113pub mod output;
114/// Path resolution helpers for config/cache storage.
115pub mod paths;
116/// Security scanners and finding/report models.
117pub mod security;
118/// MCP server construction and transport serving.
119pub mod server;
120/// Skill discovery, parsing, and generation.
121pub mod skills;