sn-architecture
Skill8 starsChanged 7 months agoMITArchived repositoryView on GitHub
SignNow MCP Server architecture rules, layer constraints, and design philosophy. Use when working on any source code in this project — implementing features, reviewing code, writing specs, planning, or testing. Covers the Thin Translator philosophy, stateless design, layer access matrix, dependency rules, and known gotchas. Do NOT use for git commits or documentation-only tasks.
- Reads credentials
In this repository8 other files it gives its agents.
- AGENTS.mdAGENTS.md
- CLAUDE.mdCLAUDE.md
- .github/copilot-instructions.mdCopilot instructions
- git-commitSkill
- sn-implementationSkill
- sn-planningSkill
- sn-spec-writingSkill
- sn-testingSkill
The file
We split this skill into the rules it gives an agent
4 rules. About 0 are common, 0 are distinctive, and 4 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈0
Distinctive · estimate
This author's own choices. Worth a look.
4
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 68
Every API response goes through tools/models.py.
- Very specific: line 86
Every tool must be registered in tools/__init__.py → register_tools() and documented in README.md.
- Very specific: line 92
RSA key regenerated silently: if OAUTH_RSA_PRIVATE_KEY PEM is missing — invalidates all JWTs.
- Very specific: line 102
Do NOT modify without explicit instruction: pyproject.toml, pytest.ini, AGENTS.md.
≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
SignNow MCP Server — Architecture
Identity
This server is a stateless translation layer between AI agents and the SignNow API. It adds zero noise and carries only the signal the agent needs. Every design decision reinforces this identity.
Guiding Principles
| Principle | Rule |
| Thin Translator | Zero state, zero caching, zero business logic that belongs in the agent. |
| Stateless | No in-memory state between requests, no session objects, no module-level mutable state, no singletons. |
| Tool Minimization | Fewer tools with broader capability. One tool decides internally whether to call document vs. document-group API. |
| Token Efficiency | Every field in a response costs money and context. Carry only the minimum data the agent needs for its next decision. Omit nulls, empty lists, metadata. |
| Testability | Every business logic function is unit-testable by injecting a mocked SignNowAPIClient. If a design makes testing harder, the design is wrong. |
| Specific Errors | Every error message names the operation, entity (with IDs), and cause. |
| YAGNI | Don't add functionality until it's actually needed. No future-proofing for hypothetical requirements. |
| No Infrastructure Coupling | No AWS/GCP/Azure assumptions. |
Layer Architecture
Agent Request
→ Transport (Starlette / STDIO / SSE)
→ Tool Orchestrator (tools/signnow.py)
→ Token Resolution (TokenProvider)
→ Business Logic (tools/<feature>.py)
→ API Client (signnow_client/client_*.py)
→ SignNow API
→ Response Model (tools/models.py)
→ AgentLayer Definitions & Access Rules
| # | Layer | Location | May Import | Must NOT Import |
| 1 | API Models | signnow_client/models/ | pydantic only | sn_mcp_server.*, signnow_client/client*.py |
| 2 | API Client | signnow_client/client_*.py | Layer 1, signnow_client/exceptions.py, httpx (via base class) | sn_mcp_server.* (NO upward imports) |
| 3 | Tool Response Models | sn_mcp_server/tools/models.py | pydantic, Layer 1 types (for references) | Raw API passthrough |
| 4 | Tool Business Logic | sn_mcp_server/tools/<feature>.py | Layer 2 (client), Layer 3 (models) | Starlette, other tool modules, token resolution |
| 5 | Tool Orchestrator | sn_mcp_server/tools/signnow.py | Layer 4, TokenProvider | Business logic in orchestrator body |
| 6 | Auth | sn_mcp_server/auth.py, token_provider.py | signnow_client, config | Tools layer |
| 7 | Transport | sn_mcp_server/app.py, cli.py | server.py, config.py, auth.py | Tools directly, API client directly |
The One Rule That Matters Most
Dependency arrow is strictly downward: sn_mcp_server → signnow_client. Never the reverse. Any import from sn_mcp_server inside signnow_client is an immediate reject.
Key Patterns
Token Flow
Token resolution belongs in the orchestrator (tools/signnow.py) via _get_token_and_client(). Business logic functions receive token: str as a parameter — they never resolve tokens themselves.
Response Curation
Every API response goes through tools/models.py. Never return raw SignNow JSON. Each field must justify: "Does the agent need this for its next decision?" If no — omit.
Error Handling
# ✅ Specific — operation + entity + cause
raise ValueError(f"Cannot send invite for document '{document_id}': no signers configured")
# ❌ Vague — no context
raise ValueError("Something went wrong")Secrets
Tokens, passwords, API keys, PEM content must NEVER appear in logs, errors, or tool responses. Use _mask_secret_value() for diagnostic output.
Tool Registration
Every tool must be registered in tools/__init__.py → register_tools() and documented in README.md.
Gotchas
- auth.py module-level side effects. Importing
auth.pytriggers config load → RSA keygen → stdout print → client creation. In tests, mock or avoid importing directly. - No token caching. Password grant fires a network call on EVERY tool invocation.
- RSA key regenerated silently if
OAUTH_RSA_PRIVATE_KEYPEM is missing — invalidates all JWTs. .envread from CWD, not project root.- Empty env vars become defaults silently.
OAUTH_ISSUER=""→http://localhost:8000. - Middleware order matters. Starlette wraps LIFO: Bearer → TrailingSlash → CORS → App.
- BearerJWT middleware bypassed in password-grant mode.
- Both
/sseand/mcpmounted. Legacy SSE + modern Streamable HTTP. redirect_targetexclusion. Request models dropredirect_targetwhenredirect_uriis absent.
Sacred Files
Do NOT modify without explicit instruction: pyproject.toml, pytest.ini, AGENTS.md.
Reference Docs
AGENTS.md— project governance constitutionARCHITECTURE.md— authoritative architectural specification
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

