Document and lock stable MCP tool, error and provenance contracts

Open
  • Is something wrong?
#44 0 comments 0 reactions 0 assignees View on GitHub

Maintainers usually reply within 1 day

Nobody has claimed this yet.

Assessment

Difficulty
4/5
Estimated time
3-5 days
Newbie friendliness
45/100
Issue type
Feature
Clarity
Mostly clear
Activity status
Active
Tech stack
javascript, node.js
Domain
api, documentation

Research direction

Start with src/index.js, src/config.js, README.md, and the protocol tests; read AGENTS.md and docs/PROJECT_CONTEXT.md first. Inventory the public tools and compare their runtime schemas with the documented IDs, errors, annotations, provenance fields, versioning policy, and output limits. Done means protocol tests cover the listed cases and documentation matches the runtime contracts; reconcile the final contracts after feature dependencies land.

Written by the indexing model from the issue text.

Description

area:backend area:docs help wanted priority:medium type:chore

Part of #28 · Target: Release readiness / v1

Goal and scope

Inventory public tools and standardize documented IDs, error codes, partial/unsupported semantics, annotations and source/freshness fields without unnecessary breaking changes. Define versioning/migration policy and a bounded-output contract.

Implementation starting points

src/index.js, src/config.js, README.md, protocol tests. Follow AGENTS.md and docs/PROJECT_CONTEXT.md; reuse existing authorization, safe-error and synthetic-fixture patterns. New runtime dependencies need a documented reason.

Dependencies and readiness

Ready to discuss/start independently against current master.

Out of scope

No broad unrelated refactor, pretending every tool is read-only when local preference setters write, or exposing raw exceptions.

Acceptance criteria and test plan

Protocol tests cover valid/invalid inputs, errors, backward compatibility, output limits and tool annotations. Documentation matches actual runtime schemas and explains new tool discovery/restart. Reconcile final contracts after feature dependencies land.

Run the relevant offline tests, npm run check and git diff --check; runtime changes also require npm test and npm audit. Report checks not run. No faculty credentials or private course material are required for a contribution.

Contributing

Comment here before starting so the maintainer can coordinate the approach and avoid duplicate work. Fork the repository, branch from master, and open a focused PR referencing this issue. No assignee or delivery deadline is set; required checks and review apply.

Dominant language
JavaScript
Stars
0
Forks
0
Avg merge
1h 25m
Merged PRs (30d)
13

Getting set up

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

More from mahmutmft/courses-mcp

All issues in mahmutmft/courses-mcp

Similar issues

More JavaScript issues

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.